Troubleshooting

“Database not initialized”#

• Confirm DatabaseServiceProvider is registered.
• Confirm application.bootstrap() has completed before resolving model services.
• Check DATABASE_URL / DATABASE_FILE and the installed driver.
• Confirm the import runs on the server, not in a Client Component.

Provider does not boot#

• Verify the provider is passed to Application.configure().use(...).
• Check constructor arguments; configured provider instances and provider classes are distinct forms.
• Remember that providers are de-duplicated by constructor during bootstrap.
• Inspect the first boot error; downstream missing-token errors may be secondary failures.

Service token cannot be resolved#

• Confirm the relevant provider registered the service.
• Ensure all required providers are included.
• Use runtime imports for injected classes when reflection metadata is required; import type erases the value.
• Verify token identity and package versions to avoid duplicate copies of a package.

Mail appears to send but no email arrives#

• Check the effective transport. The console provider logs messages rather than delivering them.
• Verify SMTP credentials, sender address, DNS/domain verification, and provider logs.
• Send a controlled test message from the production environment.

Upload fails#

• Confirm the local directory exists and is writable.
• Validate the input is a web File supported by the runtime.
• Check provider registration and selected provider ID.
• Inspect the StorageResult error rather than assuming a URL was returned.

Localization key is missing#

• Confirm the dictionary loader includes the requested locale and namespace.
• Check nested key spelling and case.
• Test ICU placeholders and plural branches.
• Ensure server and client components use the same active locale.

Next.js redirects or not-found behavior breaks#

Do not swallow all thrown errors inside generic wrappers. The kernel explicitly preserves known Next.js redirect/not-found control-flow errors in some bootstrap and event handling paths, but application code can still break them if it catches and converts the error.