{"record":{"id":"839f76740884faba","repo":"toeverything/AFFiNE","slug":"nosurfacemodelerror","errorCode":"NoSurfaceModelError","errorMessage":"This doc is missing surface block in edgeless.","messagePattern":"This doc is missing surface block in edgeless\\.","errorType":"exception","errorClass":"BlockSuiteError","httpStatus":null,"severity":"critical","filePath":"blocksuite/affine/blocks/root/src/edgeless/edgeless-root-service.ts","lineNumber":119,"sourceCode":"  }\n\n  get viewport() {\n    return this.std.get(GfxControllerIdentifier).viewport;\n  }\n\n  get zoom() {\n    return this.viewport.zoom;\n  }\n\n  get crud() {\n    return this.std.get(EdgelessCRUDIdentifier);\n  }\n\n  constructor(std: BlockStdScope, flavourProvider: { flavour: string }) {\n    super(std, flavourProvider);\n    const surface = getSurfaceBlock(this.doc);\n    if (!surface) {\n      throw new BlockSuiteError(\n        ErrorCode.NoSurfaceModelError,\n        'This doc is missing surface block in edgeless.'\n      );\n    }\n    this._surface = surface;\n  }\n\n  private _initReadonlyListener() {\n    const doc = this.doc;\n\n    const slots = this.std.get(EdgelessLegacySlotIdentifier);\n\n    let readonly = doc.readonly;\n    this.disposables.add(\n      effect(() => {\n        if (readonly !== doc.readonly) {\n          readonly = doc.readonly;\n          slots.readonlyUpdated.next(readonly);","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/toeverything/AFFiNE/blob/26c515e050211269e911f7d9cfe162a26c83ed98/blocksuite/affine/blocks/root/src/edgeless/edgeless-root-service.ts#L101-L137","documentation":"Thrown in the EdgelessRootBlockService constructor when getSurfaceBlock(this.doc) returns null — i.e. the doc has no surface block, which edgeless mode requires to hold vector/gfx primitive elements. Error code NoSurfaceModelError (a fatal-tier code > 10000). Construction of the service aborts, so the edgeless root block cannot initialise.","triggerScenarios":"Mounting/initialising an edgeless root block on a doc that has no surface block. Happens when a doc was created as a page-only doc (no surface added), when the surface block was deleted, or when a custom doc-construction pipeline skipped adding 'affine:surface'.","commonSituations":"Opening a page-mode doc in edgeless mode without first ensuring a surface block; corrupted/incomplete docs; custom doc factories that omit the surface block; migrations that drop the surface block.","solutions":["Before entering edgeless mode, ensure the doc has a surface block: if !doc.root || !getSurfaceBlock(doc), add 'affine:surface' to the root before mounting the edgeless root block.","If building a doc programmatically, always add a surface block alongside the page root when edgeless is supported.","Run a repair migration over older docs to insert a missing surface block."],"exampleFix":"// before\n// doc has no surface block -> EdgelessRootBlockService constructor throws\n\n// after\nimport { getSurfaceBlock } from '@blocksuite/affine-block-surface';\nif (!getSurfaceBlock(doc)) {\n  doc.addBlock('affine:surface', {}, doc.root!.id);\n}\n// now safe to initialise edgeless root service","handlingStrategy":"validation","validationCode":"import { getSurfaceBlock } from '@blocksuite/affine-block-surface';\nfunction ensureSurface(doc) {\n  if (!getSurfaceBlock(doc)) {\n    doc.captureSync();\n    doc.addBlock('affine:surface', {}, doc.root.id);\n  }\n}","typeGuard":"import { getSurfaceBlock } from '@blocksuite/affine-block-surface';\nfunction hasSurfaceBlock(doc): boolean {\n  return !!getSurfaceBlock(doc);\n}","tryCatchPattern":null,"preventionTips":["Always create a surface block when constructing a doc that will use edgeless mode.","Run a repair migration that inserts a surface block into older page-only docs.","Never delete the surface block of a doc that may be opened in edgeless mode."],"tags":["edgeless","surface-block","no-surface-model","doc-init"],"backgroundTag":null,"analyzedSha":"26c515e050211269e911f7d9cfe162a26c83ed98","analyzedAt":"2026-08-12T13:15:16.447Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}