mlflow/mlflow · critical

An MLflow experiment ID is required, please provide the expe

Error message

An MLflow experiment ID is required, please provide the experimentId option to init, or set the MLFLOW_EXPERIMENT_ID environment variable

What it means

init() requires an experiment ID, from the experimentId option or the MLFLOW_EXPERIMENT_ID environment variable. Without it the SDK cannot target an experiment for trace storage and throws before proceeding to further validation.

Source

Thrown at libs/typescript/core/src/core/config.ts:247

 *       span.setOutputs({ result });
 *       return result;
 *     }
 *   );
 * }
 * ```
 */
export function init(config: MLflowTracingInitOptions): void {
  const trackingUri = config.trackingUri ?? process.env.MLFLOW_TRACKING_URI;
  const experimentId = config.experimentId ?? process.env.MLFLOW_EXPERIMENT_ID;

  if (!trackingUri) {
    throw new Error(
      'An MLflow Tracking URI is required, please provide the trackingUri option to init, or set the MLFLOW_TRACKING_URI environment variable',
    );
  }

  if (!experimentId) {
    throw new Error(
      'An MLflow experiment ID is required, please provide the experimentId option to init, or set the MLFLOW_EXPERIMENT_ID environment variable',
    );
  }

  if (typeof trackingUri !== 'string') {
    throw new Error('trackingUri must be a string');
  }

  if (typeof experimentId !== 'string') {
    throw new Error('experimentId must be a string');
  }

  const databricksConfigPath =
    config.databricksConfigPath ?? path.join(os.homedir(), '.databrickscfg');

  // Validate non-Databricks URIs
  if (!isDatabricksUri(trackingUri) && !isValidHttpUri(trackingUri)) {
    throw new Error(

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Pass experimentId explicitly in init().
2. Set the MLFLOW_EXPERIMENT_ID environment variable.
3. Create an experiment in the MLflow UI/API (mlflow.create_experiment) and use its ID.
4. Use experimentId '0' (Default experiment) for local testing.

Example fix

// before
init({ trackingUri: 'http://localhost:5000' });
// after
init({ trackingUri: 'http://localhost:5000', experimentId: '0' });

const experimentId = configExperimentId ?? process.env.MLFLOW_EXPERIMENT_ID;
if (!experimentId) {
  throw new Error('Set MLFLOW_EXPERIMENT_ID or pass experimentId to init()');
}
init({ trackingUri, experimentId });

function hasExperimentId(c: { experimentId?: string }): c is { experimentId: string } {
  return typeof c.experimentId === 'string' && c.experimentId.length > 0;
}

try {
  init(initOptions);
} catch (err) {
  if ((err as Error).message.includes('experiment ID is required')) {
    console.error('Create an experiment and set MLFLOW_EXPERIMENT_ID');
  }
  throw err;
}

When it happens

Trigger: Calling init({ trackingUri: '...' }) with no experimentId and MLFLOW_EXPERIMENT_ID unset.

Common situations: New MLflow experiments not created yet so no ID is available; env var defined in one environment but not another; copying sample code that omits experimentId.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• An MLflow Tracking URI is required, please provide the track
• The MLflow Tracing client is not configured. Please call ini
• mlflow: tracing is disabled (missing trackingUri/experimentI
• trackingUri must be a string
• experimentId must be a string

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/e1f5aaa8e7da7c61. Report an issue: GitHub.