Ottili Coder

Coder doctor and troubleshooting

How to diagnose Ottili Coder with the Coder doctor and fix common problems with runs, validation, cloud runs, Git, Desktop and company context – using the real platform CLI commands.

Overview

The Coder doctor* is the guided diagnostic you run when Ottili Coder does not behave as expected. It checks the environment that runs Coder and points to the most likely cause with concrete resolution steps. The command belongs to the platform CLI* (ottili) and is called ottili doctor troubleshoot.

Ottili Coder is publicly available as a Public Beta (BETA)*. Individual capabilities carry their own maturity status — cloud runs are in beta, and direct cloud deployment is planned (PLANNED). The doctor helps when you operate a self-hosted or local Docker environment; for users of the surfaces only (chat, CLI, Desktop, Cloud) the section "Common Coder problems and solutions" below applies.

When to use the Coder doctor

Use the doctor when:

a Coder run is stuck or keeps failing,
the services that run Coder are unreachable,
ports collide or configuration is missing,
you want to check system health before fixing an error.

The doctor runs against the local, Docker-based deployment* (containers ottili_one_postgres, ottili_one_redis, network ottili_one_network, service registry config/service_registry.yaml, environment variables in keys/.env). When Ottili operates the execution for you (Ottili Cloud), the underlying health is managed by Ottili — the common-problems section is the relevant guide there.

Running the Coder doctor

Run the doctor with auto-detection, jump to a specific category, or list all categories:

ottili doctor troubleshoot --auto
ottili doctor troubleshoot --category database_connectivity
ottili doctor troubleshoot --list-categories

With --auto the doctor runs configuration and health checks and suggests the matching category. With --category you jump straight to the suspected cause. The interactive selection prompts for the category when several are found.

Available issue categories

Category	Meaning
`database_connectivity`	PostgreSQL is not reachable or not responding
`service_health`	One or more services are unhealthy or unreachable
`port_conflicts`	Multiple services claim the same port
`configuration_errors`	Missing or invalid configuration parameters
`dependency_failures`	Dependencies are unavailable or unhealthy
`resource_exhaustion`	System resources (CPU, memory, disk) are exhausted
`network_issues`	Network connectivity problems between services

Each category delivers a guided diagnostic with symptoms, steps, concrete commands and per-step verification.

Health check

Complementary to the doctor, you check individual services with the health command, locally or scoped to a service, configuration only, or port collisions only:

ottili health check
ottili health check --service unified_api
ottili health check --config-only
ottili health check --ports-only

Further tools, also available in the platform CLI, are ottili troubleshoot wizard (interactive assistant), ottili troubleshoot service <service> (service startup failure), ottili troubleshoot database (database connection) and ottili troubleshoot analyze <service> (AI-powered root-cause analysis).

Common Coder problems and solutions

A run is stuck or failing

Check the chosen mode* (Ask, Plan, Build, Fix, Review, Stabilize, Deploy, Full Run). Build, Fix, Stabilize, Deploy and Full Run may change files; Ask and Plan only analyze/plan. See [Coder modes](/docs/coder-modes).
Inspect the run logs for exception or error lines; retry with a more targeted mode (e.g. Fix for a concrete error).
For cloud runs, remember they are Beta (BETA)* — see [Understand feature status labels](/docs/understand-feature-status-labels).

Validation loop fails

Validation loops check tests, types, lint and security gates; a task counts as done only once the gates pass. On failure:

read the validation message and fix the specific check (test, type, lint, secret/dependency),
retry the run — the loop uses retries and explicit failure states,
use the Fix* or Review* mode to clarify the root cause. See [Validation](/docs/coder-validation).

Cloud runs (Beta) and deployment

Cloud runs* are Beta (BETA): the same task queue runs in Ottili Cloud* so local machines are not tied up. Individual limitations are possible. See [Local, Cloud and Hybrid runs](/docs/coder-local-cloud-hybrid-runs).
Deployment* (direct cloud delivery) is planned (PLANNED)* — until the public destination is wired, Coder prepares validated results. Do not claim that direct deployment is already available. See [Deployment](/docs/coder-deployments) and [Product lifecycle and feature status](/docs/product-lifecycle-and-feature-status).
How Ottili ONE labels maturity publicly is explained in [Product lifecycle and feature status](/docs/product-lifecycle-and-feature-status).

Git integration

Coder works in your existing repository: a branch per run, a commit per task, a pull request for review, branch protection. If the GitHub connection fails:

check the GitHub app / connector and its permissions,
make sure a repository is connected to the workspace,
for branch-protection conflicts, approve the PR manually. See [Git integration](/docs/coder-git).

Desktop app

The Ottili Coder Desktop* app for Windows, macOS and Linux carries the available (AVAILABLE) status. If it does not start:

check sign-in (Sign in with Ottili* / One Login) and the company context,
make sure the app points at the current Coder environment,
on sync problems, restart the app and sign in again.

Company context and sign-in

Every Coder run belongs to exactly one company (company_id). If actions are assigned to the wrong company, check the active company context in your session. See [Platform layer and product layer](/docs/platform-layer-and-product-layer) and [Installation](/docs/coder-installation).

Security checks

Ottili Security Check* reviews dependency and secret risk into the same task system. When a check fails it becomes visible as a validation error — fix the reported risk before the run counts as done. See [Coder security](/docs/coder-security).

Status and availability

Capability	Status
Repository analysis	Available (AVAILABLE)
Plans	Available (AVAILABLE)
Task queues	Available (AVAILABLE)
Agents	Available (AVAILABLE)
Validation loops	Available (AVAILABLE)
CLI	Available (AVAILABLE)
Desktop	Available (AVAILABLE)
Cloud runs	Beta (BETA)
Deployment (delivery)	Planned (PLANNED)
Security checks	Available (AVAILABLE)

Source: canonical feature-status registry config/product_truth/coder_feature_status.yaml. How Ottili ONE labels maturity publicly is explained in [Understand feature status labels](/docs/understand-feature-status-labels).

[Ottili Coder overview](/docs/ottili-coder)
[Coder modes](/docs/coder-modes)
[Validation](/docs/coder-validation)
[Git integration](/docs/coder-git)
[Coder security](/docs/coder-security)
[Deployment](/docs/coder-deployments)
[Local, Cloud and Hybrid runs](/docs/coder-local-cloud-hybrid-runs)
[Installation](/docs/coder-installation)
[Understand feature status labels](/docs/understand-feature-status-labels)
[Product lifecycle and feature status](/docs/product-lifecycle-and-feature-status)
[Platform layer and product layer](/docs/platform-layer-and-product-layer)
[What is Ottili ONE?](/docs/what-is-ottili-one)

Was this article helpful?