paperclipai/paperclip · error · Error

RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET is not a valid bucket

Error message

RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET is not a valid bucket name

What it means

Thrown by validateProtocolEvalHistoryDestination when the bucket value fails the S3 bucket-name regex ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ (3-63 chars, lowercase alphanumerics/dots/hyphens, no leading/trailing hyphen or dot). The env var RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET must name a valid S3 bucket for publishing eval history.

Source

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

function json(value) {
  return `${JSON.stringify(value, null, 2)}\n`;
}

async function loadObject(path) {
  const value = JSON.parse(await readFile(path, "utf8"));
  if (value === null || Array.isArray(value) || typeof value !== "object") {
    throw new Error(`Expected a JSON object: ${path}`);
  }
  return value;
}

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 ||

View on GitHub (pinned to 01ad858492)

Solutions

Set RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET to the exact S3 bucket name in lowercase (e.g. paperclip-eval-history).
Remove invalid characters (uppercase, underscores); S3 forbids them.
Ensure the value is not empty or an ARN/URL — pass just the bucket name.

Example fix

// before
RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET=My_Bucket
// after
RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET=my-bucket

Defensive patterns

Strategy: validation

Validate before calling

if (!/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(process.env.RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET ?? '')) throw new Error('bucket name must be a valid S3 bucket name (3-63 lowercase chars)');

Prevention

Store the bucket name in lowercase without underscores in your env/CI config.
Validate env vars at pipeline start with a preflight script.
Use the bare bucket name, never an ARN or URL.

When it happens

Trigger: Running the publish script with RUNNER_PROTOCOL_EVAL_HISTORY_S3_BUCKET unset, empty, containing uppercase/underscores, or shorter than 3 / longer than 63 characters.

Common situations: Typo or missing env var in CI; using a bucket alias or ARN instead of the raw bucket name; leftover underscores or uppercase in the configured name.

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/99c425b87bc9559f. Report an issue: GitHub.