paperclipai/paperclip · error · Error

must be a Discord snowflake ID

Error message

${label} must be a Discord snowflake ID

What it means

snowflake() normalizes and validates that a Discord ID string is a bare decimal number of 17-20 digits (a Discord snowflake). This template error names the offending field (applicationId, guildId, or botUserId) so the operator knows which configured value is malformed.

Solutions

1. Enable Developer Mode in Discord, right-click the server/app, and use 'Copy ID' to get the raw numeric snowflake
2. Print/inspect the failing config value and strip whitespace, quotes, or URL prefixes so only digits remain
3. Verify the value length is 17-20 digits (older IDs may be 17-18; padding a short number will not help — get the real ID)

Example fix

// before
DISCORD_GUILD_ID=https://discord.gg/myserver
// after
DISCORD_GUILD_ID=1234567890123456789

const isSnowflake = (v) => typeof v === "string" && /^\d{17,20}$/.test(v.trim());
if (!isSnowflake(process.env.DISCORD_GUILD_ID)) throw new Error("DISCORD_GUILD_ID must be a 17-20 digit snowflake");

const isSnowflake = (v) => typeof v === "string" && /^\d{17,20}$/.test(v.trim());

When it happens

Trigger: Calling verifyDiscordBot (or any consumer of applicationId/guildId/botUserId) with a config value that contains letters, whitespace-padded non-numeric text, is too short/long, or is empty after trim; passing a full Discord mention or URL instead of the raw ID.

Common situations: Copy-pasting a Discord channel/invite link instead of the server ID; using developer-mode 'Copy ID' on the wrong entity; an env var left blank or containing quotes; trimming bugs leaving stray characters.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid Discord command registration scope
• ACPX profile requires exact model ; received
• ACPX model must not be empty
• ACPX provider identity contains an invalid permission mode
• ACPX provider identity contains invalid lifetime fences

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

Appendix: source

Thrown at server/src/services/chat-discord.ts:108

]);

export interface DiscordBotIdentity {
  botAvatarUrl?: string;
  botExternalId: string;
  botLabel: string;
  botUsername: string;
  providerAccountId: string;
  providerAccountLabel: string;
}

function requestSignal(): AbortSignal {
  return AbortSignal.timeout(REQUEST_TIMEOUT_MS);
}

function snowflake(value: string, label: string): string {
  const normalized = value.trim();
  if (!/^\d{17,20}$/.test(normalized)) {
    throw new Error(`${label} must be a Discord snowflake ID`);
  }
  return normalized;
}

function bigint(value: string | undefined): bigint {
  try {
    return BigInt(value ?? "0");
  } catch {
    return 0n;
  }
}

async function discordJson<T>(
  fetchImpl: typeof globalThis.fetch,
  token: string,
  path: string,
  operation: string,
): Promise<T> {

View on GitHub (pinned to 01ad858492)