different-ai/openwork · error · InvalidEnvKeyError

reserved_env_key

reserved_env_key

Error message

Environment variable name is reserved for OpenWork internals: ${key}

What it means

Error thrown when a user attempts to set an environment variable whose name is reserved for OpenWork internals (e.g., names the server itself manages or injects, such as PORT, OPENWORK_* variables, or other protected keys). This guard prevents user-supplied values from overriding internal server configuration. Fix by choosing a non-reserved variable name; check the reserved-name list in env-file.ts to see which keys are protected.

Source

Thrown at apps/server/src/env-file.ts:206

    return run;
  }

  async list(): Promise<EnvRecord[]> {
    await this.ensureLoaded();
    return this.variables.slice();
  }

  async upsertMany(entries: EnvEntry[]): Promise<void> {
    return this.enqueueMutation(async () => {
      await this.ensureLoaded();
      const now = Date.now();
      const next = new Map(this.variables.map((entry) => [entry.key, entry] as const));
      for (const entry of entries) {
        if (!isValidEnvKey(entry.key)) {
          throw new InvalidEnvKeyError(entry.key, "invalid_env_key");
        }
        if (isReservedEnvKey(entry.key)) {
          throw new InvalidEnvKeyError(entry.key, "reserved_env_key");
        }
        next.set(entry.key, { key: entry.key, value: entry.value, updatedAt: now });
      }
      const nextVariables = Array.from(next.values()).sort((a, b) => a.key.localeCompare(b.key));
      await writeStore(this.path, nextVariables);
      this.variables = nextVariables;
    });
  }

  async delete(key: string): Promise<boolean> {
    return this.enqueueMutation(async () => {
      await this.ensureLoaded();
      const before = this.variables.length;
      const nextVariables = this.variables.filter((entry) => entry.key !== key);
      if (nextVariables.length === before) return false;
      await writeStore(this.path, nextVariables);
      this.variables = nextVariables;
      return true;

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Choose a non-reserved key name for your variable (avoid OPENWORK_* and other reserved prefixes)
2. If overriding an internal setting is needed, use the dedicated server configuration surface instead of the env store
3. Filter reserved keys out of imported env dumps before upserting

Example fix

// before
await envStore.upsertMany([{ key: "OPENWORK_HOME", value: "/tmp/x" }]);
// after
await envStore.upsertMany([{ key: "MY_OPENWORK_HOME", value: "/tmp/x" }]);

if (entries.some(e => isReservedEnvKey(e.key))) throw new Error("reserved keys present");

try { await envStore.upsertMany(entries); } catch (e) { if (e instanceof InvalidEnvKeyError && e.code === "reserved_env_key") { /* pick another name */ } else throw e; }

When it happens

Trigger: Attempting to upsert a key matching a reserved name (e.g. OPENWORK_* prefixed or other internal identifiers), typically to override agent/server behavior through the user env store.

Common situations: Users trying to override OpenWork's own configuration vars; automation scripts echoing internal keys back into the store; importing an env dump from a machine where internal vars were exported.

Related errors

• invalid_env_key
• Agent context diagnostics timeout must be between 1 ms and 3
• Invalid cloud provider sync response.
• Invalid cloud provider sync status.
• Invalid cloud provider sync status response.

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/1f364b0403cd000d. Report an issue: GitHub.