JuliusBrussee/caveman · error · Error

caveman agent: context id is required

Error message

caveman agent: context id is required

What it means

Thrown by the context() builder when options.id is empty or only whitespace (id.trim() === ''). Context ids key the segment in the Context IR and lock digest, so an untrimmable-to-nonempty id is rejected at definition time.

Source

Thrown at packages/agent/src/primitives.ts:348

  readonly privacy: PrivacyClass;
  readonly opaque: boolean;
  readonly ttlTurns?: number;
}

export function context(options: {
  id: string;
  kind: ContextKind;
  source: string | FileSource;
  stability: ContextStability;
  safety?: SafetyClass;
  priority?: ContextPriority;
  recovery?: RecoveryKind;
  cacheRegion?: CacheRegion;
  privacy?: PrivacyClass;
  opaque?: boolean;
  ttlTurns?: number;
}): ContextDefinition {
  if (options.id.trim() === "") throw new Error("caveman agent: context id is required");
  if (options.ttlTurns !== undefined && (!Number.isSafeInteger(options.ttlTurns) || options.ttlTurns <= 0)) {
    throw new Error("caveman agent: context ttlTurns must be a positive integer");
  }
  const definition: ContextDefinition = {
    kind: "context",
    id: options.id,
    segmentKind: options.kind,
    source: options.source,
    stability: options.stability,
    safety: options.safety ?? "S0",
    priority: options.priority ?? "required",
    recovery: options.recovery ?? "none",
    cacheRegion: options.cacheRegion ?? (options.stability === "build" ? "frozen_prefix" : "live_zone"),
    privacy: options.privacy ?? "local_sensitive",
    opaque: options.opaque ?? false,
    ...(options.ttlTurns === undefined ? {} : { ttlTurns: options.ttlTurns }),
  };
  return Object.freeze(definition);

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Give each context segment a stable non-empty id, e.g. 'system-prompt' or 'tool-docs'
2. When ids are generated, fall back to a derived default: options.id = raw?.trim() || fallbackName
3. Validate context definitions in config loading with a required-non-empty check before building the agent

Example fix

// before
context({ id: fileName ?? '', kind: 'system', source: sys, stability: 'build' });

// after
context({ id: fileName?.trim() || 'system-main', kind: 'system', source: sys, stability: 'build' });

function requireContextId(raw: unknown, fallback?: string): string {
  const id = typeof raw === 'string' ? raw.trim() : '';
  if (id === '') { if (fallback) return fallback; throw new Error('context id is required'); }
  return id;
}

function isNonEmptyContextId(value: unknown): value is string { return typeof value === 'string' && value.trim() !== ''; }

When it happens

Trigger: Calling context({ id: '' }) or context({ id: ' \t' }). Note that an id of whitespace-surrounded text like ' sys ' passes (only the trimmed value is checked), but blank strings do not.

Common situations: Generating ids from file paths or dynamic data where the source string is occasionally empty; template literals that interpolate an undefined variable into ''; config lists with a missing id field defaulting to empty.

Related errors

• caveman agent: context ttlTurns must be a positive integer
• caveman agent: eval id is required
• option not found
• cave_harness_adapter_version_invalid
• cave_harness_model_invalid

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/4d09f97b8808e1bd. Report an issue: GitHub.