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 |
| Extension 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. For an npm installation, run teloa open, or run teloa open --print-url to get the local sign-in link |
teloa up reports that this installation and the current command package have different versions | The existing installation is not replaced automatically. To switch versions and keep your data, run teloa stop, then teloa upgrade --to <version> |
Models and employees
If you installed with npm, run teloa doctor first; it also works before the first startup. If the npm check fails, inspect the version on PATH: npm 11.12.1 or a later 11.x is required. If the Linux terminal sandbox check fails, inspect bubblewrap, user namespaces, or Landlock kernel support. A model response or working page does not prove that restricted commands can run. Do not disable the sandbox to clear the error. Each check in doctor --json has ok and message; failed checks also have a remedy. Exit code 1 means that at least one check failed.
Test the model in a regular conversation first. If that also fails, inspect the model connection. If only one employee fails, check its active status, run configuration, business scope and knowledge access.
If a group gets no response, check that you selected or mentioned the right employee. 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 employee 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.
Report a security issue
See the Teloa AI Security reporting guidance for channels across projects. The security site also publishes an agent identity and authorization security baseline derived from Teloa development. Use the online self-assessment tool to review evidence and gaps in a specific deployment. The baseline defines assessment goals; it does not establish that the product meets every requirement.
Choose the reporting channel for the affected area:
- Teloa Community app (including its background service): report problems in teloa-ai/teloa Issues, or use the feedback form, which requires no sign-in.
- Marketplace resources (AI employees, AI teams, apps, skills and others): prefer public teloa-ai/marketplace Issues for general problems and security concerns. Include the resource page link, resource ID and version so we can identify it.
If the issue could have major impact, such as remote code execution, widespread key exposure or access to private user data, we suggest first reporting it privately to security@teloa.ai. Email reports do not require a GitHub account.
Include the affected scope, version and redacted reproduction conditions. Keep real keys, passwords or sign-in tokens, personal data and unpublished exploit steps out of public reports; we suggest sharing sensitive details privately.
Contact product support
Use Send feedback to report product issues, documentation errors or suggestions. No sign-in is required. Leave a contact email if you would like a reply. Feedback is stored privately, and a successful submission returns a feedback reference number. The link is available in the top navigation and at the bottom of each article; the product also provides it on the About page.
support@teloa.ai is the primary inbox for product support, issues and feedback. For business and partnerships, contact hi@teloa.ai.
What to include in a report
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 data directory. Distinguish a model producing no result from the interface failing to show a result that already exists.