mastra-ai/mastra · error · DuplicateEnvironmentVariableKeyError

Environment variable keys must be unique

Error message

Environment variable keys must be unique

What it means

collectEnvironmentVariables converts editor rows of key/value pairs into an env-var record. Before assigning a value it validates that each trimmed, non-empty key is unique; a duplicate key would silently overwrite a previous value, so the library throws DuplicateEnvironmentVariableKeyError to force the user to fix the form instead.

Source

Thrown at packages/playground-ui/src/lib/env-file/env-file.ts:54

      duplicates.add(key);
    } else {
      seen.add(key);
    }
  }

  return duplicates;
}

export function collectEnvironmentVariables(rows: readonly EnvironmentVariableEntry[]): Record<string, string> {
  const envVars: Record<string, string> = {};
  const seen = new Set<string>();

  for (const row of rows) {
    const key = row.key.trim();
    if (!key) continue;

    if (seen.has(key)) {
      throw new DuplicateEnvironmentVariableKeyError(key);
    }

    seen.add(key);
    envVars[key] = row.value;
  }

  return envVars;
}

/**
 * Parse text in `.env` file format into key-value entries.
 *
 * Handles:
 * - `KEY=value`
 * - Blank lines and comment lines (`#`)
 * - Double-quoted and single-quoted values
 * - Multi-line quoted values, such as private keys
 * - Values containing `=`

View on GitHub (pinned to 75dd419e61)

Solutions

1. Find the duplicate key reported by the error and remove or rename one of the rows in the editor.
2. Deduplicate rows before calling collectEnvironmentVariables if you build rows programmatically (keep the last entry if override semantics are desired).
3. Trim/normalize keys when constructing rows so accidental whitespace variants do not create near-duplicates.
4. Add UI-level duplicate detection (disable save / highlight the offending row) to catch it before submission.

Example fix

// before
const rows = [{ key: ' API_KEY ', value: 'a' }, { key: 'API_KEY', value: 'b' }];
const vars = collectEnvironmentVariables(rows); // throws

// after
const rows = [{ key: 'API_KEY', value: 'b' }]; // single, deduplicated entry
const vars = collectEnvironmentVariables(rows);

const keys = rows.map(r => r.key.trim()).filter(Boolean);
const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
if (dupes.length) throw new Error(`Duplicate env keys: ${[...new Set(dupes)].join(', ')}`);

function hasUniqueKeys(rows: { key: string }[]): boolean {
  const keys = rows.map(r => r.key.trim()).filter(Boolean);
  return new Set(keys).size === keys.length;
}

try {
  const vars = collectEnvironmentVariables(rows);
} catch (e) {
  if (e instanceof DuplicateEnvironmentVariableKeyError) {
    highlightRowWithKey(e.key); // surface duplicate to the user
  } else throw e;
}

When it happens

Trigger: Calling collectEnvironmentVariables (via useCustomEnvironmentVariablesEditor or the envVars flow) with a rows array containing two or more rows whose trimmed key strings are identical, e.g. rows [{key:'API_KEY',...},{key:'API_KEY',...}] or keys differing only by surrounding whitespace.

Common situations: Users typing the same variable twice in the environment editor, pasting a .env file where a key is defined in two sections, or importing rows where trailing whitespace makes duplicates hard to see in the UI.

Related errors

• Invalid worker environment variable name: ${key}
• [FactorySecretEncryption] Duplicate key id "${previous.id}".
• ClaudeSDKAgent resumeData must include sessionId or continue
• CursorSDKAgent resumeData must include a message.
• CursorSDKAgent resumeData.agentId must be a string when prov

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/cd6ef3ee56d97d46. Report an issue: GitHub.