Troubleshooting
Find the cause of connection failures, missing services, development conflicts, and packaging errors.
Verified September 11, 2026
On this page
The shell cannot find trove#
Open Trove’s developer controls and install/check the shell command. Start a new terminal, then inspect the selected executable:
command -v trove
trove --version
trove curio --help
A shell command can point into an application bundle. Rebuilding another local binary does not update that bundle. Confirm the registered target before assuming the CLI and Host are the same build. If a different Host executable occupies the data directory, stop that Host normally and retry with the intended build.
Host bridge is unavailable#
bridge.host_unavailable means the page lacks the injected Host bridge. Open the Curio through trove curio dev or the installed Curio in Trove. An ordinary browser tab only renders the UI; it cannot supply native APIs. For browser tests, explicitly construct a mock client.
bridge.reloaded or bridge.disconnected means that client connection ended. Cancel obsolete UI work and establish a fresh page/client connection. Calling ready() on an explicitly disconnected client does not revive it.
Development does not start#
trove curio check --json
trove --verbose curio dev
| Symptom | Check and recovery |
|---|---|
| Initialization refuses the directory | init requires a new directory, including when the existing one is empty. Use a new path or follow the existing-project guide. |
| Missing dependencies | Run the package manager chosen for this project; preserve the SDK vendor package. |
| UI server times out | Match the manifest URL and actual server port. Dynamic ports require TROVE_DEV_PORT. |
| Address already in use | Stop the stale UI process or select another port. Use --no-start-ui --ui-url ... for an existing server. |
| Curio ID already active | End that Curio’s previous development session or give independent projects distinct IDs. |
| Host executable conflict | Check the CLI registration and running Host; a different executable cannot silently take over its data directory. |
Do not delete user data to work around a development conflict. Ctrl-C stops the current CLI session; it does not quit all Host sessions.
Requests and services fail#
| Code | Meaning and next action |
|---|---|
request.invalid_params | Check the service contract’s parameter names, types, and required fields. |
request.invalid_options | Check that timeoutMs is finite and within the SDK’s accepted range. |
request.timeout | Inspect provider logs and operation duration. Retry only if the operation is safe to repeat. |
request.cancelled | The request was canceled; settle the UI without presenting a success result. |
service.not_found | Discover registered services; install/start the intended provider. |
service.method_not_found | Inspect host.services.describe; the method may be absent or only planned. |
service.version_mismatch | Align the required version range with the installed service. |
service.contract_violation | Compare request/result/event data against the published JSON contract. |
provider.disconnected | The Backend connection ended; inspect process output and lifecycle. |
self.unavailable | The operation lacks the necessary Curio/Backend context. |
host.storage.value_too_large / host.storage.quota_exceeded | Use files for large data or reduce stored values. |
Log TroveError.code, message, and traceId when present. Do not infer automatic retry behavior from retryable: true. Check the Host capability status before implementing a planned API.
Development works but the package fails#
Check ui.entry against the build output and include its assets in package.files. Use relative asset paths, verify lazy imports, and stop the UI server while testing the installed package. The production manifest does not retain development.ui.url.
A Backend entry must be a real executable for the target platform. Check permissions, architecture, and runtime dependencies. pack --dry-run cannot prove those future build outputs are valid; run an actual pack and inspect its success result.
If a download returns a login page, make the release attachment anonymously accessible. Git authentication only covers the source index/repository; it is not forwarded to HTTP artifact downloads.
Collect a useful reproduction#
Record the Host/CLI version, macOS version and architecture, Curio ID/version, failing command, expected behavior, and actual error. Copy relevant filtered output from the debug console. Include a minimal manifest or request that reproduces the failure, after removing secrets and personal data.
Then repeat the smallest failing action in a fresh development session. See testing and debugging for log limits and the distinction between mock, native, and package verification.