ATH-MaaS/Pixelle-Video · error · HTTPException

File not found: {file_path}

Error message

File not found: {file_path}

What it means

GET file handler resolves the requested path (against an optional full_path or the output/ directory) and returns 404 when the resolved absolute path does not exist on disk. The detail includes the client-supplied file_path so the caller knows which file was not found.

Source

Thrown at api/routers/files.py:78

            "data/templates/",
            "resources/",
        ]
        
        # Check if path starts with allowed prefix, otherwise try output/
        full_path = None
        for prefix in allowed_prefixes:
            if file_path.startswith(prefix):
                full_path = file_path
                break
        
        # If no prefix matched, assume it's in output/ (backward compatibility)
        if full_path is None:
            full_path = f"output/{file_path}"
        
        abs_path = Path.cwd() / full_path
        
        if not abs_path.exists():
            raise HTTPException(status_code=404, detail=f"File not found: {file_path}")
        
        if not abs_path.is_file():
            raise HTTPException(status_code=400, detail=f"Path is not a file: {file_path}")
        
        # Security: only allow access to specified directories
        try:
            rel_path = abs_path.relative_to(Path.cwd())
            rel_path_str = str(rel_path)
            
            # Check if path starts with any allowed prefix
            is_allowed = any(rel_path_str.startswith(prefix.rstrip('/')) for prefix in allowed_prefixes)
            
            if not is_allowed:
                raise HTTPException(
                    status_code=403, 
                    detail=f"Access denied: only {', '.join(p.rstrip('/') for p in allowed_prefixes)} directories are accessible"
                )
        except ValueError:

View on GitHub (pinned to 848b054e4f)

Solutions

1. Verify the file actually exists at output/{file_path} relative to the server's working directory.
2. Confirm the server process CWD matches the directory containing output/ (docker/workdir differences are common).
3. Check filename spelling and case; URL-encode special characters in the path.
4. If the file is generated by a prior step, run/complete that step before fetching.
5. In a container, ensure the output directory is volume-mounted and persisted.

Example fix

// client-side check before requesting
import fs from 'fs';
// before
await fetch(`/api/files/${filePath}`);
// after
if (!fs.existsSync(path.join('output', filePath))) {
  throw new Error(`output/${filePath} not produced yet`);
}
await fetch(`/api/files/${encodeURIComponent(filePath)}`);

import fs from 'fs';
import path from 'path';
const resolved = path.resolve('output', filePath);
if (!fs.existsSync(resolved)) throw new Error(`File ${filePath} does not exist under output/`);
// then call GET /api/files/{filePath}

try {
  const res = await fetch(`/api/files/${encodeURIComponent(filePath)}`);
  if (res.status === 404) throw new Error(`File not found on server: ${filePath}`);
  if (!res.ok) throw new Error(`File fetch failed: ${res.status}`);
  return await res.blob();
} catch (err) {
  logger.error('File fetch failed', err);
  throw err;
}

When it happens

Trigger: GET to the files endpoint with a file_path whose resolved location (full_path or output/{file_path}) does not exist — wrong filename, file deleted or not yet generated, wrong working directory of the server, or a typo/URL-encoding mismatch in the path.

Common situations: Requesting an output artifact before the pipeline produced it; server restarted with a different CWD so relative output/ paths resolve elsewhere; filename case mismatch on case-sensitive filesystems; Docker container lacking the mounted output volume.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Path is not a file: {file_path}
• str(e)
• Template not found: {template}
• str(e)
• Task {task_id} not found

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/0fca96fd2fd26019. Report an issue: GitHub.