nocobase/nocobase · error

${env ? `Env "${envName}" is missing a base URL.` : `Env "${

Error message

${env ? `Env "${envName}" is missing a base URL.` : `Env "${envName}" is not configured. Run `nb init --ui --env ${envName}` first.`}
${env ? `Update env "${envName}" with `nb env update ${envName} --api-base-url <url>` first.` : ''}

What it means

updateEnvRuntime() refreshes the stored runtime metadata for an env by fetching the swagger schema. Before making any request it requires a base URL (from options or the saved env). If none exists, it throws an error telling the user the env is either missing a base URL (env exists) or not configured at all (no env record), with exact `nb env update`/`nb init` commands to fix it.

Source

Thrown at packages/core/cli/src/lib/bootstrap.ts:476

  role?: string;
  configFile: string;
  verbose?: boolean;
  scope?: CliHomeScope;
  quiet?: boolean;
}) {
  setVerboseMode(Boolean(options.verbose));
  const envName = options.envName ?? (await getCurrentEnvName({ scope: options.scope }));
  const env = await getEnv(envName, { scope: options.scope });
  const baseUrl = options.baseUrl ?? env?.baseUrl;
  const token = await resolveAccessToken({
    envName,
    baseUrl,
    token: options.token,
    scope: options.scope,
  });

  if (!baseUrl) {
    throw new Error(
      [
        env
          ? `Env "${envName}" is missing a base URL.`
          : `Env "${envName}" is not configured. Run \`nb init --ui --env ${envName}\` first.`,
        env ? `Update env "${envName}" with \`nb env update ${envName} --api-base-url <url>\` first.` : '',
      ]
        .filter(Boolean)
        .join('\n'),
    );
  }

  if (!options.quiet) {
    updateTask('Loading command runtime...');
  }
  try {
    if (!options.quiet) {
      printVerbose(`Runtime source: ${baseUrl}`);
    }

View on GitHub (pinned to fa42722fef)

Solutions

1. Set the base URL for the env: `nb env update <envName> --api-base-url <url>`.
2. If the env does not exist at all, run `nb init --ui --env <envName>` to configure it.
3. Verify the env name and saved settings with `nb env list` before retrying.

Example fix

// before
nb runtime --env staging  # Env "staging" is not configured...
// after
nb env update staging --api-base-url https://staging.example.com
nb runtime --env staging

// verify the env has a baseUrl before invoking the runtime command
const listed = execSync(`nb env list`, { encoding: 'utf8' });
if (!listed.includes(envName)) {
  throw new Error(`Env "${envName}" does not exist. Run \`nb init --ui --env ${envName}\` first.`);
}

function envIsConfigured(env: { baseUrl?: string } | null | undefined): env is { baseUrl: string } & Record<string, unknown> {
  return !!env && typeof env.baseUrl === 'string' && /^https?:\/\//.test(env.baseUrl);
}

try {
  execSync(`nb runtime --env ${envName}`, { stdio: 'inherit' });
} catch (err) {
  if (String(err).includes('is missing a base URL')) {
    execSync(`nb env update ${envName} --api-base-url ${process.env.NB_BASE_URL}`, { stdio: 'inherit' });
    execSync(`nb runtime --env ${envName}`, { stdio: 'inherit' });
  } else throw err;
}

When it happens

Trigger: Calling updateEnvRuntime (via the `runtime` command) with options.baseUrl unset while the target env record is absent or has no baseUrl field — e.g. an env created with only a token, or a wrong --env name pointing to a nonexistent env.

Common situations: User created an env via `nb env add <name>` without --api-base-url; typo in the `--env` flag selecting an unconfigured env; config file edited or truncated by hand; migrating config to a new machine where envs were not carried over.

Related errors

• process.env.DB_TIMEZONE="${process.env.DB_TIMEZONE}" and pro
• formatMissingRuntimeEnvError(commandToken)
• Env "${envName}" is missing a base URL. Use --api-base-url o
• DB_DIALECT is required.
• Refusing to remove env "${envName}" without confirmation in

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