nocobase/nocobase · error

Docker instance ID generation did not return an instance ID.

Error message

Docker instance ID generation did not return an instance ID.

What it means

For docker runtimes the CLI runs `docker run ... nb license generate-id --json` and expects a JSON object with an instanceId field. If the parsed payload lacks instanceId or it trims to empty, this error is thrown — the container responded successfully but did not produce the expected value.

Source

Thrown at packages/core/cli/src/commands/license/shared.ts:272

export async function generateValidatedInstanceIdFromEnvVars(envVars: Record<string, string>): Promise<string> {
  await validateLicenseDbConnectionFromEnvVars(envVars);
  return await generateInstanceIdFromEnvVars(envVars);
}

async function generateInstanceIdForDockerRuntime(
  runtime: Extract<ManagedAppRuntime, { kind: 'docker' }>,
): Promise<string> {
  const envVars = await buildRuntimeEnvVars(runtime);
  const payload = (await runDockerLicenseJsonCommand(runtime, [
    'license',
    'generate-id',
    ...buildDockerLicenseDbFlagArgs(envVars),
  ])) as { instanceId?: unknown };

  const instanceId = trimValue(payload.instanceId);
  if (!instanceId) {
    throw new Error('Docker instance ID generation did not return an instance ID.');
  }
  return instanceId;
}

export async function generateInstanceIdForRuntime(runtime: ManagedAppRuntime): Promise<string> {
  if (runtime.kind === 'docker') {
    return await generateInstanceIdForDockerRuntime(runtime);
  }

  if (runtime.kind === 'local') {
    return await generateValidatedInstanceIdFromEnvVars(await buildRuntimeEnvVars(runtime));
  }

  throw new Error(`Env "${runtime.envName}" does not support automatic instance ID generation.`);
}

export async function saveInstanceId(runtime: ManagedAppRuntime, instanceId: string): Promise<string> {
  const normalized = String(instanceId ?? '').trim();

View on GitHub (pinned to fa42722fef)

Solutions

1. Inspect the full parsed payload by running the docker command manually — the JSON likely contains an error field explaining why instanceId is absent
2. Ensure the docker runtime env has complete DB_DIALECT/DB_HOST/DB_PORT/DB_DATABASE/DB_USER/DB_PASSWORD values
3. Verify the container can reach the DB over the docker network (runtime.dockerNetworkName)
4. Update CLI and docker image to matching versions
5. If the payload shape changed, report/upgrade — older images may not return instanceId

Example fix

// before
DB_DIALECT=
DB_HOST=
// after (in the docker runtime env)
DB_DIALECT=postgres
DB_HOST=host.docker.internal
DB_PORT=5432
DB_DATABASE=nocobase
DB_USER=nocobase
DB_PASSWORD=secret

const envVars = await buildRuntimeEnvVars(runtime);
const dbKeys = ['DB_DIALECT','DB_HOST','DB_PORT','DB_DATABASE','DB_USER','DB_PASSWORD'];
const missing = dbKeys.filter((k) => !String(envVars[k] ?? '').trim());
if (missing.length) throw new Error(`Docker runtime env missing: ${missing.join(', ')}`);

function hasInstanceId(payload: unknown): payload is { instanceId: string } {
  return typeof payload === 'object' && payload !== null && 'instanceId' in payload && String((payload as any).instanceId ?? '').trim() !== '';
}

try {
  const id = await generateInstanceIdForRuntime(runtime);
} catch (e) {
  if (e.message.includes('did not return an instance ID')) {
    // container returned JSON without instanceId — inspect payload/error field via manual docker run
  }
  throw e;
}

When it happens

Trigger: The container's generate-id command returns JSON without instanceId (e.g. an error payload like {"error":"..."} still parses as JSON), or instanceId is null/empty because the DB flags passed via --db-* were incomplete or wrong inside the container.

Common situations: Env for the docker runtime missing DB_* vars so the container-side generation silently fails; image version that returns a different JSON shape; container-side DB validation failing but reported as JSON without instanceId.

Related errors

• Failed to parse Docker license command response: ${output}
• Generated instance ID is empty.
• Invalid license key format
• License key not match current environment
• Failed to remove ${label} at "${target}". The current user c

AI-assisted analysis of nocobase/nocobase@fa42722fef (2026-09-01). Data as JSON: /api/errors/2d4ffbaf5a6598a5. Report an issue: GitHub.