moeru-ai/airi · error · ActionError

TARGET_NOT_FOUND

TARGET_NOT_FOUND

Error message

Could not find ${username}

What it means

Thrown by giveToPlayer when mineflayer.bot_players[username]?.entity is falsy — the named player exists in bot_players but has no loaded entity (or is not present at all). It is an ActionError with code TARGET_NOT_FOUND and context { target: username }. A missing entity means the player is out of render distance, despawned, or offline; their entry may still exist without an entity.

Source

Thrown at integrations/minecraft/src/skills/inventory.ts:159

    log(mineflayer, `You do not have any ${name} to eat.`)
    throw new ActionError('ITEM_NOT_FOUND', `You do not have any ${name} to eat`, { item: name })
  }

  await mineflayer.bot.equip(item, 'hand')
  await mineflayer.bot.consume()
  log(mineflayer, `Consumed ${item.name}.`)
}

export async function giveToPlayer(
  mineflayer: Mineflayer,
  itemType: string,
  username: string,
  num = 1,
): Promise<void> {
  const player = mineflayer.bot.players[username]?.entity
  if (!player) {
    log(mineflayer, `Could not find ${username}.`)
    throw new ActionError('TARGET_NOT_FOUND', `Could not find ${username}`, { target: username })
  }

  // Move to player position
  await goToPlayer(mineflayer, username, 3)

  // Look at player before dropping items
  await mineflayer.bot.lookAt(player.position)

  // Drop items and wait for collection
  await dropItemsAndWaitForCollection(mineflayer, itemType, username, num)
}

async function dropItemsAndWaitForCollection(
  mineflayer: Mineflayer,
  itemType: string,
  username: string,
  num: number,
): Promise<void> {

View on GitHub (pinned to 27111382b4)

Solutions

1. Confirm the player is online and within render distance before calling; have them stand near the bot.
2. Use the exact case-correct username (check Object.keys(mineflayer.bot_players)).
3. Ask the recipient to approach the bot, then retry.

Example fix

// before
await giveToPlayer(mineflayer, 'diamond', 'Steve', 1)

// after
const target = mineflayer.bot_players['Steve']
if (!target?.entity) throw new Error('Steve is not nearby')
await giveToPlayer(mineflayer, 'diamond', 'Steve', 1)

const target = mineflayer.bot_players[username]?.entity
if (!target) throw new Error(`${username} is not nearby / has no entity`)
await giveToPlayer(mineflayer, itemType, username, num)

import { ActionError } from '../utils/errors'
function isPlayerNotFoundError(e: unknown): boolean {
  return e instanceof ActionError && e.code === 'TARGET_NOT_FOUND'
}

try {
  await giveToPlayer(mineflayer, itemType, username, num)
} catch (e) {
  if (e instanceof ActionError && e.code === 'TARGET_NOT_FOUND') {
    // ask the recipient to approach, then retry
  } else throw e
}

When it happens

Trigger: Calling giveToPlayer(mineflayer, itemType, username, num) where the username is not in bot_players, or is present but bot_players[username].entity is undefined (player out of render-distance / logged off / in another dimension).

Common situations: Recipient walked out of the bot's render distance; recipient logged off; typo in username; case mismatch (Minecraft usernames are case-sensitive in this lookup); player is in another dimension.

Related errors

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

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