{"record":{"id":"14a0990e7943174b","repo":"siyuan-note/siyuan","slug":"generate-image-failed-w","errorCode":null,"errorMessage":"generate image failed: %w","messagePattern":"generate image failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/assets.go","lineNumber":437,"sourceCode":"\t\treturn GenerateImageResult{}, err\n\t}\n\tprompt := strings.TrimSpace(request.Prompt)\n\tif prompt == \"\" {\n\t\treturn GenerateImageResult{}, errors.New(\"prompt is required for image generation\")\n\t}\n\tsize := multimodalValueOrDefault(request.Size, Conf.AI.ImageGeneration.Size)\n\tquality := multimodalValueOrDefault(request.Quality, Conf.AI.ImageGeneration.Quality)\n\toutputFormat := strings.ToLower(multimodalValueOrDefault(request.OutputFormat, Conf.AI.ImageGeneration.OutputFormat))\n\tif outputFormat != \"png\" && outputFormat != \"jpeg\" && outputFormat != \"webp\" {\n\t\treturn GenerateImageResult{}, errors.New(\"unsupported image output format\")\n\t}\n\tgenerated, err := util.NewOpenAIImageAdapter(\n\t\tprovider.APIKey, provider.BaseURL, generationModel.Name, Conf.AI.ImageGeneration.RequestTimeout,\n\t).Generate(ctx, util.GenerateImageRequest{\n\t\tPrompt: prompt, Size: size, Quality: quality, OutputFormat: outputFormat,\n\t})\n\tif err != nil {\n\t\treturn GenerateImageResult{}, markImageExecutionUnknown(fmt.Errorf(\"generate image failed: %w\", err))\n\t}\n\tif ctx.Err() != nil {\n\t\treturn GenerateImageResult{}, markImageExecutionUnknown(errors.New(\"image generation was cancelled\"))\n\t}\n\treturn GenerateImageResult{\n\t\tData: generated.Data, MIMEType: generated.MIMEType, Extension: generated.Extension, RevisedPrompt: generated.RevisedPrompt,\n\t}, nil\n}\n\n// GenerateDocumentImage 使用通用图片生成能力创建文档资源。\nfunc GenerateDocumentImage(ctx context.Context, request GenerateDocumentImageRequest) (GenerateDocumentImageResult, error) {\n\tbt, err := resolveMultimodalDocument(request.DocumentID)\n\tif err != nil {\n\t\treturn GenerateDocumentImageResult{}, err\n\t}\n\tgenerated, err := GenerateImage(ctx, GenerateImageRequest{\n\t\tPrompt: request.Prompt, Size: request.Size, Quality: request.Quality, OutputFormat: request.OutputFormat,\n\t})","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/model/assets.go#L419-L455","documentation":"Returned by GenerateImage when util.NewOpenAIImageAdapter(...).Generate(ctx, ...) returns an error. The error is wrapped with markImageExecutionUnknown, marking it as an execution-state-unknown failure: because the provider call has already started, the caller MUST NOT auto-retry (IsImageExecutionUnknown returns true). Underlying causes are network, HTTP, auth, rate-limit, or provider-side errors.","triggerScenarios":"Provider API key invalid/expired (401), rate limited (429), bad base URL, request timeout exceeded (Conf.AI.ImageGeneration.RequestTimeout), provider returned a non-2xx body, DNS/TLS failure reaching BaseURL, or the model name is rejected by the provider.","commonSituations":"User pasted an OpenAI key without image-generation entitlement; BaseURL points to a gateway that doesn't proxy /images/generations; the network dropped mid-request; the configured model name doesn't support image output.","solutions":["Do NOT auto-retry: check IsImageExecutionUnknown first and surface the error to the user.","Inspect the wrapped error for HTTP status: fix the API key (401), back off (429), or correct BaseURL/model name.","Increase Conf.AI.ImageGeneration.RequestTimeout if the provider is slow but reliable.","Verify the configured provider Protocol is openai and the model is image-capable (e.g. gpt-image-1, dall-e-3)."],"exampleFix":"// before\nres, err := model.GenerateImage(ctx, req)\nif err != nil { time.Sleep(time.Second); res, err = model.GenerateImage(ctx, req) } // WRONG\n\n// after — never auto-retry execution-unknown failures\nres, err := model.GenerateImage(ctx, req)\nif err != nil {\n    if model.IsImageExecutionUnknown(err) {\n        return fmt.Errorf(\"generation may have started; not retrying: %w\", err)\n    }\n    return err\n}","handlingStrategy":"try-catch","validationCode":"// Validate configuration before the call to catch the common pre-network causes.\nif p, m := model.Conf.AI.GetImageGenerationModel(); p == nil || m == nil {\n    return errors.New(\"image model not configured\")\n} else if p.Protocol != \"\" && p.Protocol != \"openai\" {\n    return fmt.Errorf(\"provider protocol %q unsupported for images\", p.Protocol)\n}","typeGuard":"// Identify the no-retry sentinel so callers do not auto-retry.\nfunc isImageExecUnknown(err error) bool { return model.IsImageExecutionUnknown(err) }","tryCatchPattern":"res, err := model.GenerateImage(ctx, req)\nif err != nil {\n    if model.IsImageExecutionUnknown(err) {\n        // provider call began — do NOT auto-retry; surface to user\n        return err\n    }\n    // pre-network validation error — safe to let the user correct and retry\n    return err\n}","preventionTips":["Never auto-retry an IsImageExecutionUnknown error — the provider call already started.","Verify API key, BaseURL, and model name in settings before invoking.","Raise RequestTimeout if the provider is reliably slow."],"tags":["network","ai","api","provider","no-retry"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}