shareAI-lab/learn-claude-code · warning · RuntimeError

Could not allocate a unique task ID

Error message

Could not allocate a unique task ID

What it means

create_task() allocates IDs as task_ + secrets.token_hex(4) (8 hex chars, 4 billion space) and retries up to 100 times using exclusive open('x'). If every attempt hits FileExistsError, it gives up with this RuntimeError. In practice this indicates the tasks store is pathologically full or the filesystem is misbehaving, not bad luck.

Source

Thrown at s15_integrated_harness/code.py:233

        for dependency in dependencies:
            if not _task_path(dependency).is_file():
                raise ValueError(f"Dependency not found: {dependency}")
        for _ in range(100):
            task = Task(
                id=f"task_{secrets.token_hex(4)}",
                subject=subject,
                description=description,
                status="pending",
                owner=None,
                blockedBy=dependencies,
            )
            try:
                with _task_path(task.id).open("x", encoding="utf-8") as handle:
                    json.dump(asdict(task), handle, indent=2)
                return task
            except FileExistsError:
                continue
    raise RuntimeError("Could not allocate a unique task ID")


def save_task(task: Task):
    with task_store_lock():
        path = _task_path(task.id)
        temporary = path.with_name(
            f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp"
        )
        try:
            temporary.write_text(
                json.dumps(asdict(task), indent=2), encoding="utf-8"
            )
            os.replace(temporary, path)
        finally:
            temporary.unlink(missing_ok=True)


def load_task(task_id: str) -> Task:

View on GitHub (pinned to 985456f4ad)

Solutions

1. If this happens in tests, stop patching secrets.token_hex to a constant (or clean TASKS_DIR between tests).
2. Prune or archive the tasks directory if it has grown abnormally large.
3. As a last resort, retry create_task — the collision source is usually transient in misbehaving environments.

for attempt in range(3):
    try:
        task = create_task(subject, description, blockedBy)
        break
    except RuntimeError as e:
        if "unique task ID" not in str(e):
            raise
        import time; time.sleep(0.05 * (attempt + 1))
else:
    raise

When it happens

Trigger: Hundreds of millions of task files saturating the ID space (essentially never); a filesystem or test setup where open('x') spuriously raises FileExistsError; monkeypatched secrets.token_hex returning a constant in tests.

Common situations: Unit tests patching secrets.token_hex to a fixed value with a leftover task file present; a fuzz/property test hammering create_task; extremely long-lived workspaces with enormous task counts.

Related errors

• Could not allocate a unique task ID
• Task subject cannot be empty
• Dependency not found: {dependency}
• Task file ID does not match {task_id}
• Invalid task status: {task.status}

AI-assisted analysis of shareAI-lab/learn-claude-code@985456f4ad (2026-08-14). Data as JSON: /api/errors/af8e2077cfe566d4. Report an issue: GitHub.