{"record":{"id":"a7ec11917cb7e295","repo":"toeverything/AFFiNE","slug":"gfxblockelementerror","errorCode":"GfxBlockElementError","errorMessage":"Frame model is not found","messagePattern":"Frame model is not found","errorType":"exception","errorClass":"BlockSuiteError","httpStatus":null,"severity":"error","filePath":"blocksuite/affine/blocks/frame/src/frame-manager.ts","lineNumber":224,"sourceCode":"    frame.addChildren(childElements);\n  }\n\n  private _addFrameBlock(bound: Bound) {\n    const surfaceModel = this.gfx.surface as SurfaceBlockModel;\n    const props = this.gfx.std\n      .get(EditPropsStore)\n      .applyLastProps('affine:frame', {\n        title: new Text(new Y.Text(`Frame ${this.frames.length + 1}`)),\n        xywh: bound.serialize(),\n        index: this.gfx.layer.generateIndex(true),\n        presentationIndex: this.generatePresentationIndex(),\n      });\n\n    const id = this.gfx.doc.addBlock('affine:frame', props, surfaceModel);\n    const frameModel = this.gfx.getElementById(id);\n\n    if (!frameModel || !isFrameBlock(frameModel)) {\n      throw new BlockSuiteError(\n        ErrorCode.GfxBlockElementError,\n        'Frame model is not found'\n      );\n    }\n\n    return frameModel;\n  }\n\n  private _watchElementAdded() {\n    if (!this.gfx.surface) {\n      return;\n    }\n\n    const { surface: surfaceModel, doc } = this.gfx;\n\n    this._disposable.add(\n      surfaceModel.elementAdded.subscribe(({ id, local }) => {\n        const element = surfaceModel.getElementById(id);","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/toeverything/AFFiNE/blob/26c515e050211269e911f7d9cfe162a26c83ed98/blocksuite/affine/blocks/frame/src/frame-manager.ts#L206-L242","documentation":"Thrown by FrameManager._addFrameBlock after gfx.doc.addBlock('affine:frame', ...) when gfx.getElementById(id) returns null or something that fails isFrameBlock. This means the freshly added block either was not committed/registered by the time of lookup, or the flavour/schema for 'affine:frame' is not registered so addBlock produced an unexpected model. Error code GfxBlockElementError.","triggerScenarios":"Calling the public add-frame path (FrameManager.addFrame or whatever calls _addFrameBlock) before the affine:frame schema is registered, or when the surface model passed to addBlock is invalid/missing, or when an idGenerator/transaction timing issue causes getElementById to miss the just-added block.","commonSituations":"Initialising the edgeless surface before all block schemas are registered; calling frame creation during doc load before the surface block is ready; custom builds that tree-shake the frame block; race conditions where addBlock runs inside an uncommitted transaction.","solutions":["Ensure the 'affine:frame' block schema is registered (import the frame block module / add its extension) before the edgeless editor mounts.","Ensure addBlock is called within a proper store context (doc.addBlock with a valid surfaceModel parent) and that the doc is not destroyed mid-call.","If the race is timing-related, defer frame creation until the surface block is available (gfx.surface truthy) — _watchElementAdded already guards on surface presence."],"exampleFix":"// before\n// affine:frame schema not registered -> getElementById returns null\n\n// after\nimport '@blocksuite/affine-block-frame'; // registers the frame schema\n// then mount the editor; frame creation will resolve a FrameBlockModel","handlingStrategy":"validation","validationCode":"import { isFrameBlock } from '@blocksuite/affine-block-frame';\nfunction tryAddFrame(manager, bound) {\n  if (!manager.gfx.surface) return null; // surface not ready\n  return manager.addFrame(bound);\n}","typeGuard":"import { isFrameBlock } from '@blocksuite/affine-block-frame';\nimport type { GfxBlockElementModel } from '@blocksuite/affine-model';\nfunction isFrame(model): model is FrameBlockModel {\n  return !!model && isFrameBlock(model);\n}","tryCatchPattern":null,"preventionTips":["Register the affine:frame schema before mounting edgeless.","Only add frames when gfx.surface is present and the doc is writable.","Ensure addBlock runs inside a valid store transaction with a real surfaceModel parent."],"tags":["frame","edgeless","gfx-block-element","schema-registration"],"backgroundTag":null,"analyzedSha":"26c515e050211269e911f7d9cfe162a26c83ed98","analyzedAt":"2026-08-12T13:15:16.447Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}