Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Schedules, automations and workflows never run; logs say no schedule owner | No process has VOCION_SCHEDULE_OWNER=1 (vocion-stack doesn't set it) | Set it on exactly one app process (app_env on vocion-stack), redeploy |
/sign-up returns 403 on a new install | Sign-up only accepts invites | Create the first admin with npm run user:create |
| The dashboard shows empty agents and skills | WORKSPACE_PATH unset where the app runs, or the workspace was never applied | Set it; run workspace:apply -- <path> --project <slug> |
| A workflow file is ignored | It's at workflows/<slug>.yaml | Move it to workflows/<slug>/workflow.yaml |
| A YAML setting has no effect | Unknown keys are dropped silently | Check the key against Workspace YAML |
| Apply exits 2 | Validation failed, or a {{env.NAME}} token isn't in WORKSPACE_TEMPLATE_VARS | Read the named file and field; allowlist the variable |
Load fails mentioning operations/ | 4.x-era operations folder | Convert each operation to skills/<slug>/SKILL.md |
| Every credential read throws in production | VOCION_CREDENTIAL_VAULT=local without VOCION_CREDENTIAL_VAULT_KEY | Set the key (and keep it), or switch to kms |
| App fails at boot about Langfuse | LANGFUSE_ENABLED=true with missing keys | Add the keys or set LANGFUSE_ENABLED=false |
| AgentCore turns hang or tools fail | VOCION_TOOL_ENDPOINT_URL still points at localhost, or the role lacks InvokeAgentRuntimeForUser | Use a URL AWS can reach; grant both InvokeAgentRuntime and InvokeAgentRuntimeForUser |
| Factory builds behave like 4.x | Runner image unpinned; :main is a 4.x alias | Pin VOCION_RUNNER_IMAGE to :sha-<commit> or :5.x |
| Large uploads get 403 on vocion-stack | WAF body rules (count by default) were set to block | Keep waf_body_rules_action = "count" or add an exception |
| Knowledge search returns nothing | No embeddings provider key, or a provider switch without re-embedding | Set OPENAI_API_KEY or Bedrock; re-sync sources after switching |
npm run dev fails on port 5432 | Embedded Postgres collides with the Docker one | Use npm run dev:next with dev:up, or dev alone |
| A deploy fails at the version check | The new container didn't report the pinned commit | Read /var/log/vocion-deploy-last.log; the old container is still serving |
Still stuck? Check Activity for the failing run, its Langfuse trace, and the app logs, then open an issue on vocion/vocion-core with the release tag you run.