pre-alpha

Project

Troubleshooting

implemented Updated November 20, 2026 2 min read

Each section starts with the message or symptom you see.

error: cannot load notes.main:app

Run the command from the project directory (the one with hinoki.toml) and check the module path and the attribute after the colon. Hinoki adds the current directory to the import path, but the module must still import cleanly: the text after the colon is the original exception.

Settings report a missing or unknown variable

Check the settings class's prefix= and the nested names: groups are joined with __, as in NOTES_DATABASE__URL. Print every expected name with:

hinoki settings --example

settings.Secret values are shown redacted on purpose.

The database connection fails at startup

Each worker opens its pool during startup. Check the backend URL, network reachability and the server from the same environment as the worker, and the backend notes in configure a database. While debugging, use one worker and a small pool: total connections are replicas × workers × pool size.

server.<name> is not supported by the granian server

hinoki serve refuses a setting the chosen server cannot honour, and exits with status 2. Unset it or run on Kiso, the default. See settings that apply to one server only.

cannot listen on HOST:PORT

The address is in use, or the host or port is invalid. Stop the other process or pass another --port; the command exits with status 2.

Every request answers 400 disallowed_host or 503 not_ready

400 disallowed_host: the Host header is not in allowed_hosts. 503 not_ready: the worker has not finished starting, or has begun shutting down (startup probe).

RelationNotLoaded

Relations are never loaded lazily. Name the relation in the query that needs it: select_related("author") for a single row, prefetch_related("posts") for a collection. See relations.

hinoki check reports unverifiable

The rule could not establish its promise. Read the explanation and any fix: line. Some rules inspect only declarations; checks with side effects run only with hinoki check --allow-effects.

Sync handlers answer 503 overloaded

Sync handlers and sync hooks share a bounded pool and queue. Move database and network calls to async handlers, keep sync hooks short, or size the pool; see sync and async code.

A migration is marked destructive

Read the generated SQL and the data it removes, and test it against a disposable copy before passing --allow-destructive. See migrations.

Report a problem

Collect the environment without reading settings or opening a database:

hinoki version --verbose --format json
hinoki doctor

hinoki doctor imports the project application but does not start it, run rules, connect to a database or write files. Include the Hinoki version, the command or route, the complete diagnostic and a minimal example; remove credentials and personal data first.