> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/secret/projections/troubleshooting.md).

# Troubleshooting

Use this checklist when a projection does not render or behave as expected.

### Debug in this order

#### 1. Verify the template engine

Make sure the syntax matches `templateType`.

Go Template uses a leading dot.

```yaml
{{.secrets.db.url}}
```

Liquid does not.

```yaml
{{secrets.db.url}}
```

A syntax mismatch causes parsing failures.

#### 2. Confirm the context source exists

Check that the referenced Secret, Depot, or address is valid and accessible.

Common checks:

* Secret ID is correct.
* Depot name is correct.
* The workload can access the referenced object.

#### 3. Check alias usage

If you define `contextAlias: "db"`, reference it through that alias.

```yaml
projection:
  secrets:
    - id: "my-database-secret"
      contextAlias: "db"
```

Use:

```yaml
{{.secrets.db.username}}
```

Do not mix alias-based and raw ID-based references unless both are available.

#### 4. Inspect generated paths

Projection files can conflict with reserved runtime paths.

Avoid writing to these locations unless the workload expects them:

* `/etc/dataos/config`
* `/etc/dataos/secret`
* `/etc/dataos/work`

Use a custom directory for app-managed files.

#### 5. Test locally first

Use the CLI to isolate the problem.

* Use `dataos develop use` to test projection rendering.
* Use `dataos develop resource` to validate the full resource.

#### 6. Review rendered output

After deployment, inspect the effective environment variables, generated files, and command arguments.

Check that the final values match what the application expects.

### Common issues

#### Template parsing error

```
Error: template: projection:1: unexpected "}" in operand
```

Possible causes:

* Unmatched `{{` or `}}`
* Wrong syntax for the selected engine
* Missing dot notation in Go Template

What to do:

* Recheck the expression.
* Validate `templateType`.
* Test the expression locally with a minimal context.

#### Secret not found

```
Error: secret 'my-secret' not found
```

Possible causes:

* Secret does not exist.
* Secret ID is misspelled.
* The workload lacks access.

What to do:

* Verify the secret ID.
* Confirm access in the target environment.
* Recheck the alias mapping.

#### Depot fields render as empty

Possible causes:

* Wrong depot alias
* Missing `includeSecrets: true` when secret-backed fields are required
* Incorrect field path in the template

What to do:

* Confirm the depot alias.
* Turn on secret inclusion only when needed.
* Inspect the expected depot object shape.

#### File mount conflict

```
Error: projection file directory cannot be the same as config mount path
```

Possible causes:

* The projection targets a reserved directory.
* Another mount already uses the same path.

What to do:

* Move the file to a custom directory.
* Recheck stack or workload mounts.

#### Template engine mismatch

```
Error: liquid template syntax in go-template
```

Possible causes:

* `templateType` is wrong.
* Liquid syntax is used in a Go template.
* Go template syntax is used in a Liquid template.

What to do:

* Align `templateType` with the template syntax.
* Standardize on one engine per projection block.

#### Missing runtime values

Possible causes:

* The workload context does not expose the field.
* The template references the wrong object path.
* The value exists only in another environment.

What to do:

* Test with representative context files.
* Add defaults for optional values.
* Remove assumptions about tenant-specific fields.

### Quick validation tips

* Start with one variable.
* Add files and arguments after that works.
* Keep a small local test context for repeatable checks.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/resources/secret/projections/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.