"Error initializing database" almost always means the database client never connected, and on iOS the cause is usually one of a few predictable things rather than a deep bug. A Bolt.new app that works in the web preview can hit this on a real device because the configuration, the network rules, or the startup order differ once it is a native iOS build. The good news is that the suspects are short and checkable. Here is what the error means and how to work through the common causes.
Short answer
"Error initializing database" in a Bolt.new iOS app means the database client failed to start, and the usual causes are a missing or wrong configuration for the iOS build, a connection blocked by App Transport Security, a config still pointing at localhost, or the app using the database before it finished initializing. The fix is to confirm the database URL and keys are actually present in the iOS build, ensure the endpoint is HTTPS so App Transport Security allows it, replace any localhost address with a reachable host, and make sure initialization completes before the first query. Work through those in order and the error usually resolves.
What you should know
- It means the client did not connect: the database failed to initialize.
- Web preview is not the device: config and network rules differ on iOS.
- Config is the top suspect: missing or wrong URL and keys in the iOS build.
- ATS blocks non-HTTPS: iOS refuses cleartext or non-TLS connections.
- localhost does not work on a device: a dev address fails off your machine.
What does "Error initializing database" mean?
That the code which sets up your database connection threw an error before the app could use it. Whether your Bolt app uses a hosted backend like Supabase or Firebase or a local store, the initialization step creates the client with a configuration and opens the connection, and this error means that step failed. On iOS specifically, it tends to appear when something that was fine in the web preview is different in the native build: the configuration did not travel into the iOS bundle, the network layer is stricter, or the startup timing changed. So the message is pointing at setup and connection, which is where you should look, rather than at your queries or your data.
What are the common causes on iOS?
A handful of issues account for most of these. The table lists them with the fix.
| Cause | Why it happens on iOS | Fix |
|---|---|---|
| Missing or wrong config | The DB URL or key did not make it into the iOS build | Confirm the values are set for the iOS build |
| App Transport Security block | iOS refuses a non-HTTPS or non-TLS endpoint | Use an HTTPS endpoint with a valid certificate |
| Pointing at localhost | A dev address is unreachable from a device | Use a real, reachable host, not localhost |
| Initialization race | A query runs before the client is ready | Await initialization before the first call |
| Native module not linked | A local database module is not built into the app | Ensure the native dependency is properly installed |
The most frequent are the first three: a configuration that did not reach the iOS build, an endpoint that App Transport Security blocks because it is not HTTPS, and a leftover localhost address that worked in the browser but cannot be reached from a device.
How do you fix it?
Check the suspects in order, starting with configuration. First, confirm the database URL and keys are actually present in the iOS build, since values that exist in your web environment do not automatically reach a native build; verify how your project injects them. Second, make sure the endpoint is HTTPS with a valid certificate, because App Transport Security will block a cleartext or non-TLS connection and surface it as an init failure. Third, replace any localhost or 127.0.0.1 address with a host the device can actually reach. Fourth, ensure your code awaits the database initialization before making the first query, so a race does not throw on startup. If you use a local database module, confirm the native dependency is installed and built into the app. Each check is quick, and one of them is usually the cause.
What to watch out for
The first trap is debugging your queries when the error is in setup and connection, so focus on configuration and the network first. The second is assuming the web preview proves the iOS build is configured, when env values and ATS rules differ on a device. The third is leaving a development localhost endpoint in the build. A pre-submission scan such as PTKD.com (https://ptkd.com) reads the compiled APK, AAB, or IPA against OWASP MASVS and surfaces the network endpoints and any cleartext or localhost addresses in your build, which helps you spot a misconfigured or non-HTTPS database endpoint that both breaks initialization and is a security problem. Fixing the config and endpoint is the resolution.
What to take away
- "Error initializing database" means the database client failed to start, usually from configuration, network, or startup-order issues on iOS.
- The top causes are a config missing from the iOS build, an endpoint blocked by App Transport Security, a leftover localhost address, or a query running before initialization finishes.
- Confirm the URL and keys reach the iOS build, use an HTTPS endpoint, replace localhost with a reachable host, and await initialization before the first query.
- Use a pre-submission scan such as PTKD.com to surface non-HTTPS or localhost endpoints in your build, which both break initialization and signal a security issue.
