toeverything/AFFiNE · error · Error

A fatal error for BlockSuite occurs, please contact the team

Error message

A fatal error for BlockSuite occurs, please contact the team if you find this.

What it means

handleError converts any BlockSuiteError with a fatal code (>= 10000) into a generic fatal Error that preserves the original as cause; non-fatal BlockSuiteErrors are only logged. It is the framework's last-resort escalation for unrecoverable internal failures.

Source

Thrown at blocksuite/framework/global/src/exceptions/index.ts:24

  code: ErrorCode;

  isFatal: boolean;

  constructor(code: ErrorCode, message: string, options?: { cause: Error }) {
    super(message, options);
    this.name = 'BlockSuiteError';
    this.code = code;
    this.isFatal = code >= 10000;
  }
}

export function handleError(error: Error) {
  if (!(error instanceof BlockSuiteError)) {
    throw error;
  }

  if (error.isFatal) {
    throw new Error(
      'A fatal error for BlockSuite occurs, please contact the team if you find this.',
      { cause: error }
    );
  }

  console.error(
    "A runtime error for BlockSuite occurs, you can ignore this error if it won't break the user experience."
  );
  console.error(error.stack);
}

export * from './code.js';

View on GitHub (pinned to b4c8548c09)

Solutions

1. Capture the wrapped error's message and stack trace before reporting — this generic exception always wraps a more specific cause.
2. Update BlockSuite to the latest version; many fatal internal errors are fixed upstream.
3. Report the issue at https://github.com/toeverything/blocksuite/issues with the original error and reproduction steps.

Example fix

try {
  editor.host.render();
} catch (e) {
  console.error('BlockSuite fatal error, wrapped cause:', e);
  // Report with the original error details, not just the generic message
}

When it happens

Trigger: Thrown at blocksuite/framework/global/src/exceptions/index.ts:24 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of toeverything/AFFiNE@b4c8548c09 (2026-08-18). Data as JSON: /api/errors/610da35d813b1f83. Report an issue: GitHub.