{"record":{"id":"fa698d8040c8c923","repo":"moeru-ai/airi","slug":"failed-to-reach-blocktype-result-reason","errorCode":null,"errorMessage":"Failed to reach ${blockType}: ${result.reason} — ${result.message}","messagePattern":"Failed to reach (.+?): (.+?) — (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"integrations/minecraft/src/skills/movement.ts","lineNumber":111,"sourceCode":"  blockType: string,\n  minDistance = 2,\n  range = 64,\n): Promise<Block> {\n  const MAX_RANGE = 512\n  if (range > MAX_RANGE) {\n    log(mineflayer, `Maximum search range capped at ${MAX_RANGE}.`)\n    range = MAX_RANGE\n  }\n\n  const block = getNearestBlock(mineflayer, blockType, range)\n  if (!block) {\n    throw new Error(`Could not find any ${blockType} in ${range} blocks.`)\n  }\n\n  log(mineflayer, `Found ${blockType} at ${block.position}.`)\n  const result = await goToPosition(mineflayer, block.position.x, block.position.y, block.position.z, minDistance)\n  if (!result.ok) {\n    throw new Error(`Failed to reach ${blockType}: ${result.reason} — ${result.message}`)\n  }\n  return block\n}\n\nexport async function goToNearestEntity(\n  mineflayer: Mineflayer,\n  entityType: string,\n  minDistance = 2,\n  range = 64,\n): Promise<boolean> {\n  const entity = getNearestEntityWhere(\n    mineflayer,\n    entity => entity.name === entityType,\n    range,\n  )\n\n  if (!entity) {\n    log(mineflayer, `Could not find any ${entityType} in ${range} blocks.`)","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/moeru-ai/airi/blob/27111382b4a79a7e983289d6e983a06af185ed0f/integrations/minecraft/src/skills/movement.ts#L93-L129","documentation":"Thrown by goToNearestBlock after getNearestBlock succeeds but the subsequent goToPosition returns result.ok === false. The wrapped PathfindResult carries a reason of 'timeout' | 'stagnation' | 'noPath' | 'error' | 'interrupted' and a human-readable message. This is a plain Error; the failure is in pathfinding execution, not block discovery.","triggerScenarios":"The target block is found but the pathfinder cannot reach it: terrain blocks the path (noPath), the bot stops making progress for ~15s (stagnation), the goal exceeds the time estimate (timeout), a navigation interrupt is signalled, or pathfinding throws internally (error).","commonSituations":"Target is across a wall, ravine, or unbreakable blocks; bot is stuck in a hole or against an obstacle; server lag stalls movement so stagnation triggers; another action interrupted navigation; the goal coordinates are unreachable (floating island, lava-locked).","solutions":["Inspect result.reason — for 'noPath', clear obstacles or pick a closer target; for 'stagnation'/'timeout', retry after moving the bot; for 'interrupted', avoid concurrent navigation calls.","Break/bridge toward the target manually before re-running goToNearestBlock.","Increase minDistance so the goal is satisfied from a reachable adjacent position.","Retry once — transient stagnation/timeout often resolves on a second attempt."],"exampleFix":"// before\nconst block = await goToNearestBlock(mineflayer, 'oak_log', 2, 64)\n\n// after — handle PathfindResult failure explicitly\ntry {\n  const block = await goToNearestBlock(mineflayer, 'oak_log', 2, 64)\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Failed to reach')) {\n    // mine toward target or pick another, then retry\n  }\n  throw e\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"function isNavigationFailedError(e: unknown): boolean {\n  return e instanceof Error && /Failed to reach .*:/.test(e.message)\n}","tryCatchPattern":"try {\n  return await goToNearestBlock(mineflayer, blockType, minDistance, range)\n} catch (e) {\n  if (e instanceof Error && /Failed to reach/.test(e.message)) {\n    // parse reason: noPath -> break/bridge; stagnation/timeout -> retry once\n    await sleep(2000)\n    return await goToNearestBlock(mineflayer, blockType, minDistance, range)\n  }\n  throw e\n}","preventionTips":["Avoid concurrent navigation calls that interrupt each other.","Break or bridge toward unreachable targets before re-running pathfinding.","Retry once on transient stagnation/timeout before reporting failure."],"tags":["minecraft","navigation","pathfinding","timeout"],"backgroundTag":null,"analyzedSha":"27111382b4a79a7e983289d6e983a06af185ed0f","analyzedAt":"2026-08-12T18:33:34.132Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}