5.3 Troubleshooting
Record when the error occurred, what you did, and the redacted error message. Start with the relevant layer. Do not begin by clearing the database or reinstalling everything.
Installation and startup
| Symptom | What to check |
|---|---|
The docker command is missing | Install the Docker CLI and a working local engine, then run docker info |
| Docker cannot connect | Start the engine and inspect the current context and environment variables; do not switch to a remote environment by default |
| The container name belongs to another project | In source development, use the original source directory. This error stops initialization without stopping the existing container |
| The port is in use | Identify the process and what it serves; avoid killing services by a broad name match |
| Plugin build fails | For Compose, inspect the image build output. For source development, check Node.js, pnpm and dependencies, then run pnpm check:dsh |
| The page returns 401 or authentication fails | Open the complete link printed by the current startup; an old token will not work |
Models and colleagues
Test the model in a regular conversation first. If that also fails, inspect the model connection. If only one colleague fails, check its active status, runtime profile, business scope and knowledge access.
If a group gets no response, check that you selected or mentioned the right colleague. Look for an acknowledgement or a configuration error. Silence does not prove that a task has started; inspect the task and its run record.
Automation and Auto Dream
Check that the local service is online, the plan is enabled, the colleague can run, and the time and timezone are correct. Then check whether a run already exists for that date. Coming back online does not guarantee that every missed interval will be replayed. Check for duplicate work before running it again.
What to include in an issue
Provide the version, steps, expected result, actual result and a redacted error message. Do not include model keys, cookies, authentication URLs, database connection strings or an entire runtime directory. Distinguish a model producing no result from the interface failing to show a result that already exists.