Skip to main content
App version: 3.20250901

Troubleshooting guide

This guide collects debugging tips and guidelines for common problem situations.

Checking your Neptune version​

Neptune consists of three components, each with its own release track:

  • The web app, located at scale.neptune.ai or your self-hosted URL.
  • The neptune-scale Python library, for logging metadata to Neptune.
  • The neptune-query Python library, for fetching logged metadata from Neptune.
Solution

  • For how to check your app version, see Check the app version.

  • To check your Python package versions, use:

    pip show neptune-scale neptune-query

Debugging tips​

  • To control the type of debug information printed to the console, use the NEPTUNE_LOGGER_LEVEL environment variable.
  • For how to change the logging mode to disabled or offline, see Modes.

Errors and warnings​

For solutions and workarounds, see Neptune API errors and warnings.

FAQ​

Why did my runs disappear from the runs table?

You probably logged multiple runs with the same experiment name. When viewing runs in Experiments mode, only the latest run in each experiment is displayed.

To display all runs in the project, switch to Runs mode.

All runs tab in the Neptune app with a highlighted button for switching between all runs and experiment runs.

What's the difference between sys/id and sys/custom_run_id?
  • sys/custom_run_id is the run identifier you set manually via the run_id argument of the Run constructor. It's auto-generated if not provided.
  • sys/id is a legacy run identifier based on the project key. It will be removed in a future release and can be ignored.
What's the difference between tags and group tags?
Why am I facing rate limiting?

Rate limiting is a protection mechanism to ensure system stability. If you're getting rate limit errors, it's likely because you're logging data or making queries that are too frequent or too large.

For assistance, contact your platform administrator or Neptune Support.

In our code, should we run Neptune in a separate process?

No need, as there is a retry mechanism within the Neptune client. The client is safe to use from the main process, as its only function is to pass the data to the subprocess responsible for sending the data to the server.

If either the main process or the worker process is terminated, you get notified.

  • If the worker is terminated or encounters a fatal error, the main process is notified and the error callback is called.
  • If the main process is terminated, the child process exits, so no zombie processes remain.

The parent-child process setup lets us work around Python's GIL for better performance. Any errors that are non-fatal result in a retry, so anything that's reported as an error can be treated as fatal or exhausted retries.

Should we retry in case we encounter API errors?

Neptune uses a subprocess to send data asynchronously. This subprocess propagates errors to its parent, which can handle the errors using callbacks. The subprocess includes retry logic.

For details, see Error handling in callbacks.

Support​

For help, contact our Support team.