siyuan-note/siyuan · error

AI configuration is unavailable

Error message

AI configuration is unavailable

What it means

GenerateImage reads the global configuration singleton Conf and its AI section to find the image-generation provider. If Conf is nil (configuration not yet loaded/initialized) or Conf.AI is nil (AI settings never created), it cannot proceed and returns "AI configuration is unavailable".

Solutions

  1. Ensure the kernel is fully booted (util.Boot / model configuration load) before calling GenerateImage
  2. Initialize configuration in tests: call the conf init helper (model.InitConf or equivalent) before invoking GenerateImage
  3. Open Settings - AI in the app to create/save the AI configuration section, then retry

Example fix

// before (test)
result, err := model.GenerateImage(ctx, req) // Conf == nil
// after
model.InitConf()
conf.Conf.AI.ImageGeneration = ... // set provider/model
result, err = model.GenerateImage(ctx, req)
Defensive patterns

Strategy: validation

Validate before calling

if conf.Conf == nil || conf.Conf.AI == nil {
    return errors.New("AI configuration not loaded; boot the kernel or init conf first")
}

Type guard

func aiConfigReady() bool { return conf.Conf != nil && conf.Conf.AI != nil }

Try / catch

res, err := model.GenerateImage(ctx, req)
if err != nil && err.Error() == "AI configuration is unavailable" {
    // initialize/load configuration, then retry once
}

Prevention

When it happens

Trigger: Calling GenerateImage (directly or via GenerateDocumentImage) before kernel configuration is loaded — e.g. in tests or early startup — or in an environment where the AI config section was never initialized (Conf.AI == nil).

Common situations: A unit test calling GenerateImage without model.InitConf; a headless/embedded use of the model package that skipped configuration loading; a corrupted or manually edited conf.json that prevented the AI section from being populated.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/d740ef11ca2f42d2. Report an issue: GitHub.

Appendix: source

Thrown at kernel/model/assets.go:523

	}
	prepared, err := util.PrepareModelImage(
		data, documentImageMaxBytes, documentImageMaxPixels, documentImageMaxEdge,
	)
	if err != nil {
		return PreparedDocumentImage{}, err
	}
	return PreparedDocumentImage{
		Artifact: ImageArtifactRef{Kind: "image", Path: relativePath},
		Data:     prepared.Data,
		MIMEType: prepared.MIMEType,
		Prepared: prepared,
	}, nil
}

// GenerateImage 使用全局图片生成配置创建图片字节，可供文档资源、编辑器和其他图片入口复用。
func GenerateImage(ctx context.Context, request GenerateImageRequest) (GenerateImageResult, error) {
	if Conf == nil || Conf.AI == nil {
		return GenerateImageResult{}, errors.New("AI configuration is unavailable")
	}
	provider, generationModel := Conf.AI.GetImageGenerationModel()
	if err := validateImageModel(provider, generationModel); err != nil {
		return GenerateImageResult{}, err
	}
	prompt := strings.TrimSpace(request.Prompt)
	if prompt == "" {
		return GenerateImageResult{}, errors.New("prompt is required for image generation")
	}
	size := multimodalValueOrDefault(request.Size, Conf.AI.ImageGeneration.Size)
	quality := multimodalValueOrDefault(request.Quality, Conf.AI.ImageGeneration.Quality)
	outputFormat := strings.ToLower(multimodalValueOrDefault(request.OutputFormat, Conf.AI.ImageGeneration.OutputFormat))
	if outputFormat != "png" && outputFormat != "jpeg" && outputFormat != "webp" {
		return GenerateImageResult{}, errors.New("unsupported image output format")
	}
	generated, err := util.NewOpenAIImageAdapter(
		provider.APIKey, provider.BaseURL, generationModel.Name, Conf.AI.ImageGeneration.RequestTimeout, ResolveAIProviderHeaders(provider),
	).Generate(ctx, util.GenerateImageRequest{

View on GitHub (pinned to 9f775e8a12)