pre-alpha

6.5 · Project

Troubleshooting

cannot load module:attribute

Run the command from the application checkout and check both the module path and attribute spelling. hinoki adds the current directory when importing targets, but the package still needs to be importable Python code.

Settings report a missing or unknown variable

Check the settings class's prefix= and nested field names. Nested groups use __, for example APP_DATABASE__URL. Run hinoki settings module:SettingsClass --example to inspect expected names. settings.Secret values are redacted by design.

Database connection fails at startup

The database module opens a pool in each worker's startup. Confirm the selected backend URL, network reachability and database availability from the same environment as the worker. Check the backend-specific URL, TLS and migration limits in Configure a database. Use one worker and a small pool while debugging; total maximum connections are replicas × workers × pool size.

Foreign-key attributes do not trigger queries. Add select_related("author") or prefetch_related("posts") to the query that needs the relation.

hinoki check reports unverifiable

The rule could not establish its promise. Read the diagnostic explanation and any fix: line. Some rules inspect only declarations; effectful checks require the explicit --allow-effects flag.

A sync handler or auth provider stalls

Sync code runs on a bounded executor and can saturate. Prefer async database and network calls in async handlers. See sync and async for limits and server settings for worker configuration.

A migration is marked destructive

Review the generated SQL and the data it may remove. Test the change against a disposable database backup before using --allow-destructive. See migrations.

If the issue persists, include the Hinoki version, the command or route, the complete diagnostic, and a minimal example. Remove credentials and user data first.

For a version report, run hinoki version --verbose --format json. The output includes installed runtime details without reading application settings or opening a database.

For a consolidated local report, run hinoki doctor. It imports the selected app target, but does not start its lifecycle, run rules, connect to a database or write files. Use the focused commands above for database and migration state.