moeru-ai/airi · error · ActionError

UNKNOWN

UNKNOWN

Error message

Invalid position to break block at

What it means

Thrown by breakBlockAt (world-interactions.ts:220) with code UNKNOWN when any of x, y, or z is null (compared with ==, so undefined also matches). This is a defensive precondition check before any block math runs; no mineflayer state is touched. No context payload.

Source

Thrown at integrations/minecraft/src/skills/actions/world-interactions.ts:220

  }
}

/**
 * Break a block at the given position.
 * @param mineflayer The mineflayer instance.
 * @param x The x coordinate.
 * @param y The y coordinate.
 * @param z The z coordinate.
 * @throws {ActionError} When the block is unbreakable or missing tools.
 */
export async function breakBlockAt(
  mineflayer: Mineflayer,
  x: number,
  y: number,
  z: number,
): Promise<void> {
  if (x == null || y == null || z == null) {
    throw new ActionError('UNKNOWN', 'Invalid position to break block at')
  }

  // Calculate the block position by rounding down the coordinates
  const blockPos = new Vec3(Math.floor(x), Math.floor(y), Math.floor(z))
  logger.log(`Attempting to break block at ${blockPos}`)

  // Log bot position
  const botPos = mineflayer.bot.entity.position
  logger.log(`Bot position: ${botPos.x.toFixed(1)}, ${botPos.y.toFixed(1)}, ${botPos.z.toFixed(1)}`)

  // Calculate the actual block under the bot's feet
  const feetPos = new Vec3(Math.floor(botPos.x), Math.floor(botPos.y - 1), Math.floor(botPos.z))
  logger.log(`Actual block under feet: ${feetPos}`)

  // Use the provided position directly
  const targetPos = blockPos

  const block = mineflayer.bot.blockAt(targetPos)

View on GitHub (pinned to 27111382b4)

Solutions

1. Validate coordinates are numbers before calling: typeof x === 'number' && Number.isFinite(x).
2. Default missing axes to the bot's current position (bot.entity.position) when sensible.
3. Add a TypeScript signature that rejects undefined (remove optionality) so the call site fails to compile.
4. Log the offending coordinate in the caller to catch the source of the null.

Example fix

// before
await breakBlockAt(bot, pos.x, pos.y /* z missing */) // throws UNKNOWN

// after
if (pos.x == null || pos.y == null || pos.z == null) throw new Error('bad pos')
await breakBlockAt(bot, pos.x, pos.y, pos.z)

if (x == null || y == null || z == null || !Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
  throw new TypeError(`invalid coordinates: ${x}, ${y}, ${z}`)
}
await breakBlockAt(mineflayer, x, y, z)

const areValidCoords = (x: unknown, y: unknown, z: unknown): boolean =>
  typeof x === 'number' && typeof y === 'number' && typeof z === 'number'
  && Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)

try {
  await breakBlockAt(mineflayer, x, y, z)
} catch (e) {
  if (e instanceof ActionError && e.code === 'UNKNOWN' && e.message.includes('Invalid position')) {
    // fix or default the coordinates, then retry
  } else throw e
}

When it happens

Trigger: Call breakBlockAt with null/undefined coordinates: an unset variable, a missing field from a parsed schematic, or an optional parameter that was not provided. The == null check deliberately catches both null and undefined.

Common situations: Caller forgot to pass one coordinate, schematic parser returned undefined for a missing axis, position came from an object whose property was renamed, or a default-parameter chain resolved to undefined.

Related errors

• Unknown action: ${step.tool}
• UNKNOWN
• ITEM_NOT_FOUND
• ITEM_NOT_FOUND
• TARGET_NOT_FOUND

AI-assisted analysis of moeru-ai/airi@27111382b4 (2026-08-12). Data as JSON: /api/errors/65787c2c2a74975d. Report an issue: GitHub.