> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vegalake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose common VegaLake scope, permission, validation, connection, cluster, run, and lineage issues.

# Troubleshooting

Start with scope and identity before changing resources. Many empty states and authorization failures are correct results for the wrong organization, workspace, or permission set.

| Symptom                            | Check                                                                                                                                    |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| A page or action is missing        | Confirm the selected organization/workspace and the current user's roles, groups, and direct permissions.                                |
| An API returns unauthorized        | Confirm the service base URL, bearer token or API key, credential expiry, and operation security requirements.                           |
| An API returns forbidden/not found | Verify tenant path IDs and collection or instance permission; protected resources may not be disclosed.                                  |
| Validation fails                   | Compare required fields, enums, selection modes, and cross-field constraints with the generated API schema.                              |
| A secret is unavailable            | Confirm vault scope, secret existence, and permission to the namespace instance. Never copy the value into logs.                         |
| Connection validation fails        | Check connector type, host/network reachability, database settings, and secret references. Current saved connection support is Postgres. |
| A cluster cannot start             | Check node type selection, minimum/maximum nodes, capacity, current status, and lifecycle permissions.                                   |
| Auto-stop is rejected              | Enable it only with a positive auto-stop time.                                                                                           |
| A QuickFlow run fails              | Check connection validation, cluster readiness, source/destination configuration, selection rules, and run details.                      |
| A schedule does not launch work    | Confirm it is active, the QuickFlow still exists, and its cluster and connections remain usable.                                         |
| VegaGraph search is empty          | Check workspace/context, filters, labels/type selection, and permission to search or view matching entities.                             |
| Lineage is incomplete              | Check traversal direction, depth, relationship filters, field/entity granularity, and whether edges were ingested.                       |

## Escalate safely

Record request ID, time, service, operation, organization/workspace IDs, and a redacted error category. Do not send access tokens, API keys, passwords, backup codes, connection credentials, or secret values. Contact [support@vegalake.com](mailto:support@vegalake.com) when the checks above do not isolate the problem.