> 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/references/dataos-resources/vulcan/troubleshooting.md). # Troubleshooting Vulcan rejects bad requests early so you do not waste engine cycles or end up with half-broken results. When a query, plan, or API call fails, you get a specific error code and message. This page lists the errors you can hit at validation or request time, what triggered each, and how to fix it. If you arrived from a `4xx` response, search this page for the code or message. ## Query validation errors These come back when you submit SQL to the query API and Vulcan rejects it before any execution. | Error | When it fires | Fix | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `PARSE_ERROR` | The SQL does not parse against the target gateway dialect, or uses an unsupported construct. | Recheck the SQL against the gateway dialect, replace dialect-specific functions, and simplify deeply nested syntax. | | `DATA_MANIPULATION_DETECTED` | The raw SQL endpoint accepts read-only statements only, but the query contains `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `REPLACE`, `CREATE`, `DROP`, `ALTER`, `TRUNCATE`, or similar. | Send a read-only query (`SELECT`, `WITH`). Move data modification into a model or job. For a semantic query, use the semantic endpoint. | | `NOT_FOUND` | The query references a table or model that does not exist in the selected environment. | Check the name for typos, confirm the environment, and run `vulcan plan ` if the model is not applied there. | | `TABLE_EXTRACTION_ERROR` | The SQL parsed, but the lineage step could not extract table references. | Simplify the SQL, split large nested queries into CTEs, and avoid unusual dialect-specific patterns. | | `NORMALIZATION_ERROR` | The query parsed, but serializing it back to normalized SQL failed. | Simplify the query structure and remove edge-case syntax. | | `RECENT_FAILURE` | An identical query failed recently, so Vulcan blocks immediate retry to stop noisy retry loops. The guard fingerprints the *normalized* SQL, so cosmetic edits (whitespace, casing) will not bypass it. | Fix the original failure first, then resubmit. To retry intentionally, set `retry_on_recent_failure=true`. | ## Request validation errors These come from request-body checks before any SQL or semantic logic runs. | Error | Fix | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Invalid `ttl` (`ttl must be 0 or between 5 and 43200 minutes`) | Use `0` for never-expire, or `5` to `43200`. Values `1` to `4` are rejected. | | Oversized `meta` (`meta field exceeds 10KB limit`) | Trim `meta` to small tracing context (request ID, user ID). Store large payloads elsewhere and reference by ID. | | Generic `422` validation error | Compare your payload against the API schema at `/redoc` or `/openapi.json`. Confirm every required field is present and types match. | ## Semantic query and transpiler errors These appear when you query the semantic layer. | Error | When it fires | Fix | | ------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `API.QUERY.POST_PROCESSING_REQUIRED` | A query needs post-processing but `disable_post_processing=true` was set. | Resend with `disable_post_processing=false`. | | `TRANSPILER.QUERY.INVALID` | The semantic query is structurally invalid or references the wrong objects. | Verify measures, dimensions, filters, and joins. Preview with `vulcan transpile` first. | | `TRANSPILER.SERVICE.UNAVAILABLE` | The transpiler service was unreachable, timed out, or is still initializing. | Check its health endpoint and network connectivity, then retry. | | `TRANSPILER.UPSTREAM.ERROR` | The transpiler crashed while processing the request. | Check transpiler logs; retry if transient; escalate if a valid query fails consistently. | | `SQL_TRANSPILATION_ERROR` | An incoming dialect could not be converted to the target backend dialect. | Use simpler, more portable syntax and confirm the declared client dialect matches what you send. | | `SEMANTIC_QUERY_ERROR` | Semantic SQL compilation failed, usually from bad aggregation or grouping. | Make sure every non-aggregated column is in `GROUP BY` and field references are correct. | {% hint style="success" %} Run `vulcan transpile` locally on the same payload before submitting it to the API. You see the error immediately and the SQL it would produce. See [Semantic model and components](/references/dataos-resources/vulcan/core-concepts/semantic-model-and-components.md#querying-the-semantic-layer). {% endhint %} ## Authentication and authorization errors These come from Heimdall and the auth middleware. | Error | When it fires | Fix | | ----------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `COMMON.AUTH.UNAUTHORIZED` | Missing or malformed authorization header. | Send `Authorization: Bearer ` and confirm a proxy did not strip it. | | `COMMON.AUTH.INVALID_TOKEN` | The token is expired, malformed, revoked, or unusable. | Refresh or replace the token; confirm it was issued for the correct tenant. | | `COMMON.AUTH.FORBIDDEN` | The user is authenticated but access policies deny the request. | Check roles or tags, update the access policy, or use a service account with the right permission. | | `COMMON.INTERNAL.ERROR` during auth | Heimdall timed out, returned invalid data, or was unreachable. | Check Heimdall health and connectivity, then retry. | ## Environment and initialization errors | Error | When it fires | Fix | | ------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `Environment '' not found` | The environment does not exist in the state store. | Verify the name, create it with `vulcan plan `, and confirm with `vulcan environments`. | | Transpiler client not initialized | The API started but the transpiler client was not wired up. | Read API startup logs, verify transpiler config (host, port, credentials), and restart. | | Environment context manager not initialized | Startup failed before the environment context manager was built. | Read API startup logs, fix the initialization failure, and restart. | ## Metric and semantic catalog errors | Error | When it fires | Fix | | ----------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `Metric '' not found` | The metric is not in the loaded catalog for this environment. | Check the name and confirm the metric is defined and loaded in the selected environment. | | `Model '' not found` | The model or alias is not in the environment catalog. | Verify the name, confirm an alias resolves, and confirm the model has been planned into this environment. | | `Unknown slice(s) for metric ...` | The request asked for slices the metric does not expose. | Use only the metric's defined slices. | | `Metric is misconfigured ... slice '.ref' is missing` | A metric slice lacks its required semantic reference. | Add the missing slice reference to the metric definition. | ## Semantic field definition errors These fail at validation when Vulcan loads the semantic layer, almost always from an edited `models/semantics/*.yml` file. | Error | Fix | | ----------------------------------------------------------- | ----------------------------------------------------------- | | `Field '' must have at least one role` | Mark the field as a column, dimension, measure, or segment. | | `Field '' cannot be both measure and segment` | Pick one role, or define two separate fields. | | `Field '' has time properties but is_dimension=False` | Set `is_dimension=true`, or remove the time properties. | | `Field '' has measure_type but is_measure=False` | Set `is_measure=true`, or remove `measure_type`. | ## Perspective and result errors Perspectives are saved views over a statement's result. | Error | Fix | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `SLUG_CONFLICT` | Pick a different slug or use a suggested one. | | `Statement not found` | Verify the `statement_id` and the system/environment you posted against. | | `Statement must be SUCCESS` / `Primary statement must be SUCCESS` | Build a perspective only from a successful statement; wait for it or fix a failed query. | | `Statement has no result` / `Primary statement has no result` / `Cache result not found` | Check worker logs and object store; re-run the statement. | | `Only owner can update perspective` | Update from the owner account, or transfer ownership first. | | `Access denied` | Add the user to `allowed_user_ids` or make the perspective public. | | `Result not available. Statement status: ...` / `Result not available. Primary status: ...` | Poll the statement detail endpoint and fetch only when status is `SUCCESS`. | | `Format '' not supported` | Use `parquet`, `json`, `yaml`, or `csv`. | | `Invalid columns requested: ...` | Request only columns in the result schema. | ## File API and time range errors | Error | Fix | | -------------------------------- | ----------------------------------------------------------------------------------------------- | | `Path outside project directory` | Use a path relative to the project root; do not use `../`. | | `Path matches ignore patterns` | Use a path not covered by an ignore rule, or update the rule only if exposing the file is safe. | | `start_ts must be <= end_ts` | Swap the timestamps so the start is earlier than or equal to the end. | ## Still stuck? * Run `vulcan transpile` on the failing payload to see the generated SQL and earlier errors. See [Semantic model and components](/references/dataos-resources/vulcan/core-concepts/semantic-model-and-components.md#querying-the-semantic-layer). * Look at the API logs around the failing request. For deployed runtimes, see the [Deployment checklist](/references/dataos-resources/vulcan/deployment-checklist.md#runtime-entries). * For lifecycle questions (why a query hit cache, why deduplication kicked in, why a status looks stuck), see the [semantic query lifecycle guide](/references/dataos-resources/vulcan/incremental-by-time/semantic-query-lifecycle.md). --- # 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/references/dataos-resources/vulcan/troubleshooting.md?ask=&goal= ``` `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.