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.
A related field is not loaded¶
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.