moeru-ai/airi · error · ActionError

UNKNOWN

UNKNOWN

Error message

Invalid item name: ${itemName}

What it means

Thrown by craftRecipe when McData.getItemId(itemName) returns a falsy id, meaning the normalized name is not a registered Minecraft item in the loaded version's item registry. The library normalizes input (lowercase, spaces to underscores, appends 's' to '*plank') but if the result still is not a real item id, it aborts before any recipe lookup. Coded UNKNOWN because the item itself is unrecognized.

Source

Thrown at integrations/minecraft/src/skills/crafting.ts:35

import { goToNearestBlock, goToPosition, moveAway } from './movement'
import { getInventoryCounts, getNearestBlock, getNearestFreeSpace } from './world'

const logger = useLogger()

export async function craftRecipe(
  mineflayer: Mineflayer,
  incomingItemName: string,
  num = 1,
): Promise<boolean> {
  let itemName = incomingItemName.replaceAll(' ', '_').toLowerCase()

  if (itemName.endsWith('plank'))
    itemName += 's' // Correct common mistakes

  const mcData = McData.fromBot(mineflayer.bot)
  const itemId = mcData.getItemId(itemName)
  if (!itemId) {
    throw new ActionError('UNKNOWN', `Invalid item name: ${itemName}`)
  }

  // Helper function to attempt crafting
  async function attemptCraft(
    recipes: Recipe[] | null,
    craftingTable: Block | null = null,
  ): Promise<boolean> {
    if (recipes && recipes.length > 0) {
      const recipe = recipes[0]
      try {
        await mineflayer.bot.craft(recipe, num, craftingTable ?? undefined)
        logger.log(
          `Successfully crafted ${num} ${itemName}${craftingTable ? ' using crafting table' : ''
          }.`,
        )
        return true
      }
      catch (err) {

View on GitHub (pinned to 27111382b4)

Solutions

1. Look up the canonical id first: const mcData = McData.fromBot(mineflayer.bot); if (!mcData.getItemId(name)) ask the planner to disambiguate.
2. Match against the registry and suggest the closest valid id (Levenshtein on mcData.itemsArray).
3. Ensure the bot's minecraft-data version matches the server (mineflayer-bot protocol / mcData version).
4. For modded items, extend the registry or refuse with a user-facing 'unsupported item' message.

Example fix

// before
craftRecipe(mineflayer, 'plak', 4)

// after
const mcData = McData.fromBot(mineflayer.bot)
const name = 'plak'.replaceAll(' ', '_').toLowerCase()
if (!mcData.getItemId(name)) {
  throw new Error(`Unknown item '${name}'. Check spelling and Minecraft version.`)
}
await craftRecipe(mineflayer, name, 4)

function isValidItem(mineflayer: Mineflayer, name: string): boolean {
  const mcData = McData.fromBot(mineflayer.bot)
  const normalized = name.replaceAll(' ', '_').toLowerCase()
  return !!mcData.getItemId(normalized)
}
if (!isValidItem(mineflayer, userInput)) {
  throw new Error(`'${userInput}' is not a known item for MC ${mineflayer.bot.game.version}`)
}

try {
  await craftRecipe(mineflayer, userInput, 1)
} catch (e) {
  if (e instanceof ActionError && e.code === 'UNKNOWN' && e.message.startsWith('Invalid item name')) {
    // prompt user/planner for a corrected name
  } else throw e
}

When it happens

Trigger: Passing a display name that does not map to an id ('pickaxe' alone is not valid — must be 'wooden_pickaxe' etc.); a modded item not in the vanilla registry; a typo ('wooden_plak' ); a version mismatch (an item added in 1.20 when the bot runs 1.16); passing a block name like 'oak_log' that is valid as an item but using a wrong alias.

Common situations: LLM hallucinates a item name; modded server with custom items the registry does not know; bot connected with wrong protocol version; user gave a friendly name ('stairs') that needs a material prefix ('oak_stairs').

Related errors

• Unknown action: ${step.tool}
• UNKNOWN
• ITEM_NOT_FOUND
• UNKNOWN
• Invalid position to break block at.

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