paperclipai/paperclip · error · Error

Invalid Discord command registration scope

Error message

Invalid Discord command registration scope

What it means

createDiscordCommandRegistration validates its scope against scopeSchema before freezing the registration state. A scope object that is missing required fields or has fields of the wrong shape fails safeParse and throws this Error; no registration row or ownerId is minted.

Source

Thrown at server/src/services/chat-discord-command-registration.ts:158

  return createHash("sha256")
    .update(
      JSON.stringify(
        priorCloseCopy
          ? priorCloseCopyDefinition(id)
          : discordPaperclipCommandDefinition(id),
      ),
    )
    .digest("hex");
}

/** Persist this prepared descriptor before calling reconcile; its CAS must
 * require that durable row. Do not mint a new owner to bypass a conflict. */
export function createDiscordCommandRegistration(
  scope: DiscordCommandRegistrationScope,
): DiscordCommandRegistration {
  const parsed = scopeSchema.safeParse(scope);
  if (!parsed.success)
    throw new Error("Invalid Discord command registration scope");
  return freezeState({
    schema: "paperclip.discord.command-registration.v1",
    scope: parsed.data,
    ownerId: randomBytes(16).toString("hex"),
    phase: "prepared",
  });
}

export function parseDiscordCommandRegistration(
  input: unknown,
  scope: DiscordCommandRegistrationScope,
  /** Maintenance only; prior attempted writes and arbitrary digests stay closed. */
  allowKnownPriorDefinition = false,
): DiscordCommandRegistration | null {
  const expected = scopeSchema.safeParse(scope);
  const parsed = stateSchema.safeParse(input);
  if (!expected.success || !parsed.success) return null;
  for (const key of Object.keys(

View on GitHub (pinned to 01ad858492)

Solutions

1. Pass the complete scope object with all fields required by scopeSchema (correct applicationId, guild/scope ids, etc.).
2. Verify the Discord application/guild config values are loaded (env vars set, not empty).
3. Validate the scope with the same schema at config-load time to fail fast with a clearer message.
4. Log the Zod error (parsed.error) from safeParse to see exactly which field failed.

Example fix

// before
createDiscordCommandRegistration({ applicationId: process.env.DISCORD_APP_ID }) // env unset -> throws
// after
if (!process.env.DISCORD_APP_ID || !process.env.DISCORD_GUILD_ID) throw new Error("set DISCORD_APP_ID and DISCORD_GUILD_ID");
createDiscordCommandRegistration({ applicationId: process.env.DISCORD_APP_ID, guildId: process.env.DISCORD_GUILD_ID });

const parsed = scopeSchema.safeParse(scope);
if (!parsed.success) throw new Error('invalid Discord registration scope: ' + parsed.error.issues.map(i => i.path.join('.')).join(','));

function isValidScope(s) { return typeof s === 'object' && s !== null && typeof s.applicationId === 'string' && s.applicationId.length > 0; } // plus guildId per scopeSchema

try {
  const reg = createDiscordCommandRegistration(scope);
} catch (e) {
  if (/Invalid Discord command registration scope/.test(e.message)) {
    failFast('Discord command scope config is incomplete; check applicationId/guildId settings');
  }
  throw e;
}

When it happens

Trigger: Calling createDiscordCommandRegistration({}) or with a partially filled scope — e.g. missing applicationId/guildId or ids of the wrong format — so scopeSchema.safeParse returns success:false.

Common situations: Config loaded from env where DISCORD_APPLICATION_ID/GUILD_ID are unset; typo'd scope keys (appId vs applicationId); passing the whole Discord client object or a string instead of the scope object.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid Discord command owner identifier
• ${label} must be a Discord snowflake ID
• ${label} is not a regular file at ${canonical}.
• Claude Managed evals require exact model claude-sonnet-5
• AWS AgentCore evals require exact model global.anthropic.cla

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