{"record":{"id":"229e35aff87bf204","repo":"siyuan-note/siyuan","slug":"this-operation-is-not-supported-in-read-only-mode","errorCode":null,"errorMessage":"This operation is not supported in read-only mode","messagePattern":"This operation is not supported in read-only mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"kernel/model/onboarding.go","lineNumber":109,"sourceCode":"\tonboarding := Conf.Onboarding\n\tif !onboarding.NewUser || onboarding.Dismissed {\n\t\treturn cloneOnboarding(onboarding), false, nil\n\t}\n\n\tboxes, listErr := ListNotebooks()\n\tif listErr != nil {\n\t\treturn cloneOnboarding(onboarding), false, listErr\n\t}\n\tdocumentExists := onboarding.NotebookID != \"\" && onboarding.DocumentID != \"\" && filelock.IsExist(filepath.Join(\n\t\tutil.DataDir, onboarding.NotebookID, onboarding.DocumentID+\".sy\"))\n\tif reconcileOnboarding(onboarding, boxes, documentExists) {\n\t\tConf.Save()\n\t}\n\tif !onboarding.NewUser || onboarding.State == conf.OnboardingCompleted {\n\t\treturn cloneOnboarding(onboarding), false, nil\n\t}\n\tif util.ReadOnly || Conf.Publish.Enable {\n\t\treturn cloneOnboarding(onboarding), false, errors.New(Conf.Language(34))\n\t}\n\n\tif onboarding.NotebookID == \"\" {\n\t\tif len(boxes) > 0 {\n\t\t\tif len(boxes) == 1 && boxes[0].Name == Conf.Language(342) {\n\t\t\t\tonboarding.NotebookID = boxes[0].ID\n\t\t\t\tonboarding.State = conf.OnboardingNotebookCreated\n\t\t\t\tConf.Save()\n\t\t\t} else {\n\t\t\t\tonboarding.State = conf.OnboardingCompleted\n\t\t\t\tonboarding.NewUser = false\n\t\t\t\tConf.Save()\n\t\t\t\treturn cloneOnboarding(onboarding), false, nil\n\t\t\t}\n\t\t}\n\n\t\tif onboarding.NotebookID == \"\" {\n\t\t\tonboarding.NotebookID, err = CreateBox(Conf.Language(342))","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/model/onboarding.go#L91-L127","documentation":"Thrown by EnsureOnboarding() via Conf.Language(34) which resolves to 'This operation is not supported in read-only mode'. The onboarding flow (creating notebooks/documents for new users) is blocked when the kernel is running in read-only mode or when Conf.Publish.Enable is true (publish mode). This is a hard guard preventing data mutation in restricted deployment modes.","triggerScenarios":"Calling EnsureOnboarding() when util.ReadOnly is true or Conf.Publish.Enable is true, and onboarding.NewUser is true and not dismissed and state is not completed. The function returns early with the onboarding clone and this error instead of proceeding to create notebooks.","commonSituations":"The SiYuan kernel was launched with the --readonly flag for a deployment that only serves published content. The publish feature is enabled, making the instance read-only for viewers. A new user visits a publish-mode instance and the frontend triggers the onboarding check, which correctly refuses.","solutions":["If onboarding is needed, disable read-only mode (--readonly=false) and ensure Conf.Publish.Enable is false during the initial user setup.","For publish-mode deployments, dismiss or complete onboarding before enabling publish, or set Conf.Onboarding.NewUser=false in the config.","In the calling code, check util.ReadOnly and Conf.Publish.Enable before calling EnsureOnboarding() and skip silently or show a different message."],"exampleFix":"// before\nonboarding, created, err := model.EnsureOnboarding()\n\n// after\nif util.ReadOnly || model.Conf.Publish.Enable {\n    // Skip onboarding in read-only/publish mode\n    return\n}\nonboarding, created, err := model.EnsureOnboarding()","handlingStrategy":"validation","validationCode":"if util.ReadOnly || Conf.Publish.Enable {\n    // Skip onboarding; show a static message instead\n    return nil, false, nil\n}","typeGuard":"func canOnboard() bool {\n    return !util.ReadOnly && !Conf.Publish.Enable\n}","tryCatchPattern":null,"preventionTips":["Check util.ReadOnly and Conf.Publish.Enable before calling EnsureOnboarding().","For publish-mode deployments, complete or dismiss onboarding before enabling publish.","Do not expose onboarding-related UI elements in read-only/publish mode."],"tags":["onboarding","read-only","publish-mode","config","guard"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}