paperclipai/paperclip · error · Error

RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX must be a safe non-empty

Error message

RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX must be a safe non-empty key prefix

What it means

Thrown by validateProtocolEvalHistoryDestination when the prefix fails safety checks: after stripping leading/trailing slashes it must be non-empty and every '/'-separated segment must be non-empty and not '.' or '..'. This prevents path-traversal-style or empty S3 key prefixes in RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX.

Source

Thrown at packages/paperclip-runner/scripts/publish-runner-protocol-eval-history.mjs:82

export function validateProtocolEvalHistoryDestination({
  bucket,
  prefix,
  publicBaseUrl,
}) {
  if (!/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(bucket)) {
    throw new Error(
      "RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET is not a valid bucket name",
    );
  }
  const normalizedPrefix = String(prefix ?? "").replace(/^\/+|\/+$/g, "");
  if (
    !normalizedPrefix ||
    normalizedPrefix
      .split("/")
      .some((segment) => !segment || segment === "." || segment === "..")
  ) {
    throw new Error(
      "RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX must be a safe non-empty key prefix",
    );
  }
  const url = new URL(publicBaseUrl);
  if (
    url.protocol !== "https:" ||
    url.username ||
    url.password ||
    url.search ||
    url.hash
  ) {
    throw new Error(
      "RUNNER_PROTOCOL_EVAL_HISTORY_PUBLIC_BASE_URL must be a credential-free HTTPS URL",
    );
  }
  return {
    bucket,
    prefix: normalizedPrefix,

View on GitHub (pinned to 01ad858492)

Solutions

Set RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX to a concrete non-empty key prefix, e.g. 'eval-history/protocol'.
Remove '.' or '..' segments from the prefix.
Strip redundant leading/trailing slashes (they are trimmed, but interior empty segments are rejected).

Example fix

// before
RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX=../public
// after
RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX=public/eval-history

Defensive patterns

Strategy: validation

Validate before calling

const p = (process.env.RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX ?? '').replace(/^\/+|\/+$/g, '');
if (!p || p.split('/').some(s => !s || s === '.' || s === '..')) throw new Error('prefix must be safe and non-empty');

Prevention

Use concrete path-like prefixes with no '.' or '..' segments.
Don't leave the prefix env var empty — there is no default.
Normalize prefixes once in a shared config module.

When it happens

Trigger: Running the publish script with RUNNER_PROTOCOL_EVAL_HISTORY_PREFIX unset/empty, set to '/' or '//', or containing segments like '.' or '..'.

Common situations: Leaving the env var empty assuming a default exists; copying a file-system relative path like './out' or '..' into the prefix; trailing-slash-only value.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/bedf3a66aa65748b. Report an issue: GitHub.