unslothai/unsloth · error · RuntimeError

GGUF conversion produced a symlink, refusing to relocate it:

Error message

GGUF conversion produced a symlink, refusing to relocate it: {src}

What it means

RuntimeError raised while relocating GGUF outputs after conversion: one of the produced .gguf paths in the temp model directory (or reported by the converter) is a symlink, and the exporter refuses shutil.move on it. Moving a symlink would either copy the link itself or follow it into the save directory, which could pull in unexpected files — so the export aborts rather than relocate untrusted link targets.

Source

Thrown at studio/backend/core/export/export.py:1178

                        quantization_method = quant_method,
                        **imatrix_kw,
                        **local_token_kw,
                    )

                    # Scan only the owned root; exact reported paths cover external outputs.
                    reported = result if isinstance(result, dict) else {}
                    produced = {p for p in model_tmp_path.rglob("*.gguf") if p.is_file()}
                    produced.update(Path(f) for f in _reported_gguf_files(result) or [])
                    produced = {p for p in produced if not _is_imatrix(p, imatrix_path)}
                    modelfiles = {p for p in model_tmp_path.rglob("Modelfile") if p.is_file()}
                    reported_modelfile = reported.get("modelfile_location")
                    if reported_modelfile and Path(reported_modelfile).is_file():
                        modelfiles.add(Path(os.path.abspath(os.fspath(reported_modelfile))))

                    relocated_ggufs = []
                    for src in sorted(produced):
                        if src.is_symlink():
                            raise RuntimeError(
                                f"GGUF conversion produced a symlink, refusing to relocate it: {src}"
                            )
                        dest = os.path.join(abs_save_dir, src.name)
                        shutil.move(str(src), dest)
                        relocated_ggufs.append(dest)
                        logger.info(f"Relocated GGUF: {src.name} → {abs_save_dir}/")
                    if not relocated_ggufs:
                        raise RuntimeError(
                            "GGUF conversion produced no files: no .gguf outputs for "
                            f"{abs_save_dir}"
                        )

                    if modelfiles:
                        modelfile = sorted(modelfiles)[0]
                        if modelfile.is_symlink():
                            raise RuntimeError(
                                "GGUF conversion produced a symlinked Modelfile, "
                                f"refusing to relocate it: {modelfile}"

View on GitHub (pinned to 203007d190)

Solutions

Check the reported src path: inspect what it links to (readlink) and why the converter produced a link.
Disable symlink/dedup behavior in the converter or the cache layer hosting the temp model path.
Ensure temp export directories are real directories on the same filesystem as the save dir.
If the link target is the genuine GGUF, replace the link with the real file (copy) before re-exporting.

Example fix

# diagnose
ls -la /tmp/.../model/  # note the symlink
cp --remove-destination "$(readlink -f model_out.gguf)" model_out.gguf  # replace link with real file
# then re-run the export

Defensive patterns

Strategy: validation

Validate before calling

symlinks = [p for p in Path(model_tmp).rglob('*.gguf') if p.is_symlink()]
if symlinks:
    raise/fail_fast(f'converter emitted symlinks: {symlinks}')

Try / catch

try:
    export()
except RuntimeError as e:
    if 'symlink' in str(e):
        materialize_real_files(model_tmp); export()  # copy link targets over the links

Prevention

Run exports with real (non-symlinked) temp and cache directories.
Disable dedup/link features in converter caches.
Check converter output for links before relocation in pipelines.

When it happens

Trigger: A conversion toolchain (or a cached/converter step) emitting the .gguf as a symlink into the temp dir (e.g. hardlink/symlink deduplication in a cache); conversion running in a shared cache layout where outputs are linked rather than written; tampered or unusual converter output.

Common situations: Docker environments where the HF cache or temp dirs are symlinked; converters that dedupe identical outputs via links; running exports against a storage backend that materializes files as links.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/5578d5e1fbe49437. Report an issue: GitHub.