codex-team/editor.js · error · Error

Could not convert Block. Tool «${targetToolName}» not found.

Error message

Could not convert Block. Tool «${targetToolName}» not found.

What it means

BlockManager.convert resolves the target tool by name from the tool registry; if targetToolName is not a registered block tool, conversion aborts with this error.

Source

Thrown at src/components/modules/blockManager.ts:847

   * @param blockDataOverrides - optional new Block data overrides
   */
  public async convert(blockToConvert: Block, targetToolName: string, blockDataOverrides?: BlockToolData): Promise<Block> {
    /**
     * At first, we get current Block data
     */
    const savedBlock = await blockToConvert.save();

    if (!savedBlock) {
      throw new Error('Could not convert Block. Failed to extract original Block data.');
    }

    /**
     * Getting a class of the replacing Tool
     */
    const replacingTool = this.Editor.Tools.blockTools.get(targetToolName);

    if (!replacingTool) {
      throw new Error(`Could not convert Block. Tool «${targetToolName}» not found.`);
    }

    /**
     * Using Conversion Config "export" we get a stringified version of the Block data
     */
    const exportedData = await blockToConvert.exportDataAsString();

    /**
     * Clean exported data with replacing sanitizer config
     */
    const cleanData: string = clean(
      exportedData,
      replacingTool.sanitizeConfig
    );

    /**
     * Now using Conversion Config "import" we compose a new Block data
     */

View on GitHub (pinned to 5f45dabbe5)

Solutions

1. Register the target tool in the editor config
2. Verify the tool name against the registry before converting
3. Use editor.blocks.convert only with configured block tool names

Example fix

// before
editor.config.tools = { paragraph: Paragraph };
editor.blocks.convert(id, 'header');
// after
editor.config.tools = { paragraph: Paragraph, header: Header };
editor.blocks.convert(id, 'header');

const registered = new Set(Object.keys(toolsConfig)); if (!registered.has(targetToolName)) throw new Error('register target tool first');

const isRegisteredTool = (name: string, cfg: Record<string, unknown>): boolean => name in cfg;

try { await editor.blocks.convert(id, targetToolName); } catch (e) { if (e instanceof Error && e.message.includes('not found.')) { /* register tool, then retry */ } throw e; }

When it happens

Trigger: Internal convert invoked with a tool name absent from Tools.blockTools: unregistered tool, misspelled name, or an inline tool name.

Common situations: Same as the API-level variant: converting to a tool not present in the editor's tools config.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Block Tool with type "${newType}" not found
• Block with id "${id}" not found
• Conversion from "${blockToConvert.name}" to "${newType}" is
• Could not convert Block. Failed to extract original Block da
• Unable to move Block down since it is already the last

AI-assisted analysis of codex-team/editor.js@5f45dabbe5 (2026-08-27). Data as JSON: /api/errors/8fd64805ae9cbd74. Report an issue: GitHub.