InstantMLDocs

Troubleshooting

Fix common hosted API, SDK, API key, and importer issues.

Open .md

Work through the entry that matches your symptom — each one gives a quick check and the fix.

The SDK cannot connect

Check that the hosted API is reachable:

bash
curl https://api.instantml.ai/healthz

If the health check succeeds, confirm your SDK key is configured:

bash
test -n "$INSTANTML_API_KEY" && echo "INSTANTML_API_KEY is set"

Fix: run instantml login, export INSTANTML_API_KEY, or pass api_key="instantml_..." directly to im.init(...).

Hosted calls are unauthorized

Check that an API key is present in the environment:

bash
test -n "$INSTANTML_API_KEY" && echo "INSTANTML_API_KEY is set"

Fix: run instantml login, set INSTANTML_API_KEY, or pass api_key="instantml_..." directly to im.init(...).

Hosted calls are rate-limited

Check the X-InstantML-RateLimit-Scope header on the 429 response to see which limit you hit.

Fix for second scope: retry after the Retry-After header delay or reduce request concurrency.

Fix for monthly scope: the quota resets at the next UTC calendar month. Free and non-billable workspaces are blocked at the monthly allowance, while paid Pro and Premium API request overage is Stripe-metered. See Pricing, limits, and billing.

The dashboard does not show my run

Check the project name you used in the SDK call. project="cartpole" appears in the dashboard project selector as cartpole.

Fix: if the run was created but later logging calls failed, call run.flush() when using buffering and check SDK exceptions for the failed request.

Offline replay did not create a run

Check whether the failure happened during init() itself. Current limitation: init() still needs a reachable server because run creation is not spooled yet.

Fix: none needed for later calls — offline_dir covers failed requests made after a run already exists. Retry init() once the server is reachable.

Neptune imports fail before parsing

Check that pyarrow is installed and the input path is right.

Fix: install the import extras with pip install "instantml[imports]" and point the importer at the exported Parquet directory rather than a symlink. For the full import workflow and CLI flags, see Imports.

TensorBoard sync produces no new points

Check that the run source identity matches the original imported TensorBoard run and that the event files contain scalar summaries.

Fix: re-run the sync against the original run's source identity, or confirm the event files actually log scalars. See Imports for the sync workflow.

Generated API reference looks stale

The generated reference should match the practical API guides.

Fix: if a documented hosted route is missing, report the page URL, endpoint, and response x-request-id if a request failed.

Next steps