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 --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 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 check --json
trove --verbose dev
| Symptom | Check and recovery |
|---|---|
| Initialization refuses the directory | new 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.
Generated clients and kit updates#
bindings.stale means output is missing or differs from its contract. Run trove generate, fix reported export, contract, or path errors, then run trove check. Do not repair this by editing generated files.
kit.modified means a vendored kit was edited locally at the same version, so the CLI refuses to overwrite it. Preserve needed edits, restore a known kit version, then run trove kit and your package manager's install command. Keep application logic in project source.
For older SDKs, follow the migration steps for public imports and generated clients.
Missing runtime output#
First verify the Curio, Run ID, development or installed origin, and artifact in the debug console. Terminal and Host read the same run logs. A new run replaces the previous in-memory view; there is no disk history.
Host can only read bytes the process has written. A C/C++ library that buffers stdout until exit can produce no output during work and a burst on close. Use line buffering or explicit flush at the producer; refreshing the Host view cannot flush a library buffer. Normal shutdown allows a bounded drain, but forced termination cannot recover unflushed bytes.
Device names in output come from the plugin or its dependencies; log capture does not verify model identity. Check product information returned by the device instead of inferring a specific model from a generic VID/PID mapping.
Curio references fail#
| Symptom | Check |
|---|---|
| curio.not_installed | Use a Curio ID, not a service subnamespace; install the provider or start its dev session |
| curio.disabled | Enable the provider in Host |
| curio.no_public_services | Private Backends are not cross-Curio APIs; publish services.provides |
| service.version_mismatch | Align the installed service version and consumer requires range |
| curio.ambiguous_api | Check service-tree collisions, especially then/events and methods matching child services |
| Method type is unknown | Set bindings.services[].curio, run trove generate, include the generated .d.ts in tsconfig |
| Get succeeds but calls fail | Get does not start a process; inspect startup logs, ready, deadlines and current installation state |
No UI appearing is expected: cross-Curio calls target Backend only. Public providers can keep running and logging after their installed window closes. Closing a dev session still ends that development run.