paperclipai/paperclip · error · Error

`opencode models` timed out after ${MODELS_DISCOVERY_TIMEOUT

Error message

`opencode models` timed out after ${MODELS_DISCOVERY_TIMEOUT_MS / 1000}s.

What it means

Thrown by discoverOpenCodeModels (LOCAL discovery, models.ts) when the local `opencode models` child process does not finish within MODELS_DISCOVERY_TIMEOUT_MS (20s). This is the local-side sibling of the remote probe timeout (388); it uses runChildProcess with timeoutSec = 20 and graceSec = 3.

Source

Thrown at packages/adapters/opencode-local/src/server/models.ts:149

  }
  // Prevent OpenCode from writing an opencode.json into the working directory.
  const runtimeEnv = normalizeEnv(ensurePathInEnv({ ...process.env, ...env, ...(resolvedHome ? { HOME: resolvedHome } : {}), OPENCODE_DISABLE_PROJECT_CONFIG: "true" }));

  const result = await runChildProcess(
    `opencode-models-${Date.now()}-${Math.random().toString(16).slice(2)}`,
    command,
    ["models"],
    {
      cwd,
      env: runtimeEnv,
      timeoutSec: MODELS_DISCOVERY_TIMEOUT_MS / 1000,
      graceSec: 3,
      onLog: async () => {},
    },
  );

  if (result.timedOut) {
    throw new Error(`\`opencode models\` timed out after ${MODELS_DISCOVERY_TIMEOUT_MS / 1000}s.`);
  }
  if ((result.exitCode ?? 1) !== 0) {
    const detail = firstNonEmptyLine(result.stderr) || firstNonEmptyLine(result.stdout);
    throw new Error(detail ? `\`opencode models\` failed: ${detail}` : "`opencode models` failed.");
  }

  return sortModels(parseOpenCodeModelsOutput(result.stdout));
}

export async function discoverOpenCodeModelsCached(input: {
  command?: unknown;
  cwd?: unknown;
  env?: unknown;
} = {}): Promise<AdapterModel[]> {
  const command = resolveOpenCodeCommand(input.command);
  const cwd = asString(input.cwd, process.cwd());
  const env = normalizeEnv(input.env);
  const key = discoveryCacheKey(command, cwd, env);

View on GitHub (pinned to 67001ec6eb)

Solutions

Run `opencode models` manually on the host to see what it is waiting on.
Pre-authenticate the provider (opencode login or API key env) so model enumeration is fast.
If discovery is consistently slow and the model is known-good, set OPENCODE_ALLOW_ALL_MODELS to skip discovery.
Raise MODELS_DISCOVERY_TIMEOUT_MS only if the slowness is a known temporary condition.

Defensive patterns

Strategy: retry

Validate before calling

// Bypass discovery when the model is pre-validated.
if (isTruthyEnvFlag(env.OPENCODE_ALLOW_ALL_MODELS ?? process.env.OPENCODE_ALLOW_ALL_MODELS)) {
  return [{ id: model, label: model }]; // skip discoverOpenCodeModels
}

Try / catch

let attempt = 0;
while (true) {
  try {
    return await discoverOpenCodeModels(input);
  } catch (e) {
    if (e instanceof Error && /`opencode models` timed out after/.test(e.message) && attempt++ < 1) continue;
    throw e;
  }
}

Prevention

Pre-authenticate providers so `opencode models` is fast.
Set OPENCODE_ALLOW_ALL_MODELS when discovery is unreliable and the model is known-good.
Monitor host load; discovery timeout often tracks CPU/disk contention.

When it happens

Trigger: runChildProcess for `opencode models` returns { timedOut: true } during local model discovery (not a remote target).

Common situations: First-run provider auth check that hangs on a network call; slow disk/antivirus scanning the opencode binary; opencode stuck on an interactive prompt in a non-TTY shell; heavily loaded host.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/6149d937c2c35d9d. Report an issue: GitHub.