mudler/LocalAI · critical

[acestep-cpp] FATAL: failed to load text encoder\n

Error message

[acestep-cpp] FATAL: failed to load text encoder\n

What it means

The acestep-cpp music-generation pipeline failed at step 4: qwen3_load_text_encoder() returned false, so the Qwen3 text encoder GGUF (g_text_enc_path) could not be loaded into the Qwen3GGML struct. The function is expected to also perform backend init internally, so a failure means either the file is missing/corrupt or ggml backend allocation failed. The shim aborts generation with exit code 4 after printing this to stderr.

Source

Thrown at backend/go/acestep-cpp/cpp/goacestepcpp.cpp:195

    std::string text_str  = std::string("# Instruction\n") + instruction + "\n\n" +
                            "# Caption\n" + cap_str + "\n\n" +
                            "# Metas\n" + metas + "<|endoftext|>\n";
    std::string lyric_str = std::string("# Languages\n") + lang_str + "\n\n# Lyric\n" +
                            lyrics_str + "<|endoftext|>";

    // 3. Tokenize
    auto text_ids  = bpe_encode(&tok, text_str.c_str(), true);
    auto lyric_ids = bpe_encode(&tok, lyric_str.c_str(), true);
    int  S_text    = (int)text_ids.size();
    int  S_lyric   = (int)lyric_ids.size();

    fprintf(stderr, "[acestep-cpp] caption: %d tokens, lyrics: %d tokens\n", S_text, S_lyric);

    // 4. Text encoder forward (backend init handled inside qwen3_load_text_encoder)
    Qwen3GGML text_enc = {};
    if (!qwen3_load_text_encoder(&text_enc, g_text_enc_path.c_str())) {
        fprintf(stderr, "[acestep-cpp] FATAL: failed to load text encoder\n");
        return 4;
    }

    int                H_text = text_enc.cfg.hidden_size;  // 1024
    std::vector<float> text_hidden(H_text * S_text);

    qwen3_forward(&text_enc, text_ids.data(), S_text, text_hidden.data());
    fprintf(stderr, "[acestep-cpp] TextEncoder forward done\n");

    // 5. Lyric embedding
    std::vector<float> lyric_embed(H_text * S_lyric);
    qwen3_embed_lookup(&text_enc, lyric_ids.data(), S_lyric, lyric_embed.data());

    // 6. Condition encoder (backend init handled inside cond_ggml_load)
    CondGGML cond = {};
    if (!cond_ggml_load(&cond, g_dit_path.c_str())) {
        fprintf(stderr, "[acestep-cpp] FATAL: failed to load condition encoder\n");
        qwen3_free(&text_enc);

View on GitHub (pinned to 44413a9d06)

Solutions

1. Verify g_text_enc_path points to an existing, complete Qwen3 GGUF (check file size against the gallery manifest, re-download if truncated).
2. Run with GGML backend logging enabled (the ggml_log_cb shim already routes backend logs to stderr) to see the exact load failure before the FATAL line.
3. Confirm the file is actually the text encoder shard, not the DiT/VAE (g_dit_path) — tensor names must match the Qwen3 layout qwen3_load_text_encoder expects.
4. If backend init is the cause, check that the ggml backends bundled with the binary (CPU/CUDA/Metal) load — ggml_backend_load_all() output appears earlier in stderr.

Example fix

// before: pointing at the wrong shard
acestep_set_paths("dit.gguf", "vae.gguf", "dit.gguf"); // text enc == dit, wrong
// after: point text encoder at the Qwen3 GGUF
acestep_set_paths("qwen3_text_encoder.gguf", "vae.gguf", "acestep_dit.gguf");

// Go side, before generation:
if _, err := os.Stat(textEncPath); err != nil {
    return fmt.Errorf("text encoder missing: %w", err)
}
if fi, _ := os.Stat(textEncPath); fi.Size() < 1<<20 {
    return errors.New("text encoder file suspiciously small (truncated?)")
}

When it happens

Trigger: Calling the generate entry point with a text-encoder model path that does not exist, points at a non-GGUF or truncated file, has mismatched tensor names/architecture (not Qwen3 layout), or when ggml backend (CPU/GPU) initialization fails inside qwen3_load_text_encoder.

Common situations: Model gallery entry resolved to a wrong or partially downloaded text encoder file; user pointed --text-enc at the DiT or VAE weights instead of the Qwen3 encoder; disk-full or interrupted download left a truncated GGUF; build lacks the GPU backend the file was quantized for.

Related errors

• [acestep-cpp] FATAL: failed to load DiT from %s\n
• [acestep-cpp] FATAL: failed to load condition encoder\n
• [acestep-cpp] FATAL: silence_latent not found in %s\n
• [acestep-cpp] FATAL: cannot read GGUF metadata from %s\n
• [acestep-cpp] FATAL: failed to load BPE tokenizer\n

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/d9762586218e6961. Report an issue: GitHub.