github/spec-kit · error · OSError

Refusing to use symlinked workflow install lock: {lock_file}

Error message

Refusing to use symlinked workflow install lock: {lock_file}

What it means

Error "Refusing to use symlinked workflow install lock: {lock_file}" thrown in github/spec-kit.

Source

Thrown at src/specify_cli/workflows/_commands.py:687

    assert staged_file is not None
    return _StagedWorkflowFile(staged_file, fd)


@contextlib.contextmanager
def _workflow_install_transaction(project_root: Path):
    """Serialize workflow file swaps with their registry updates."""
    from ..shared_infra import _ensure_safe_shared_directory

    lock_dir = project_root / ".specify"
    try:
        _ensure_safe_shared_directory(
            project_root, lock_dir, context="workflow install lock directory"
        )
    except ValueError as exc:
        raise OSError(str(exc)) from exc
    lock_file = lock_dir / ".workflow-install.lock"
    if lock_file.is_symlink():
        raise OSError(f"Refusing to use symlinked workflow install lock: {lock_file}")

    flags = os.O_RDWR | os.O_CREAT
    flags |= getattr(os, "O_NOFOLLOW", 0)
    flags |= getattr(os, "O_CLOEXEC", 0)
    fd = os.open(lock_file, flags, 0o600)
    try:
        if lock_file.is_symlink():
            raise OSError(
                f"Refusing to use symlinked workflow install lock: {lock_file}"
            )
        if os.name == "nt":
            import errno
            import msvcrt
            import time

            if os.fstat(fd).st_size == 0:
                os.write(fd, b"\0")
            while True:

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Remove the symlinked workflow install lock file and retry.

When it happens

Trigger: Thrown at src/specify_cli/workflows/_commands.py:687 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/62a8e6fe3648af27. Report an issue: GitHub.