# What Happens When Cache Files Are Invalid or Corrupted in InterviewStreet's Hiring Agent

> Learn what happens when cache files are invalid or corrupted in InterviewStreet's Hiring Agent. Discover how it detects errors, logs warnings, and recomputes data to ensure a smooth workflow.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: internals
- Published: 2026-07-14

---

**When cache files are invalid or corrupted, the repository automatically detects the error, logs a warning, deletes the corrupt file, and recomputes the data from source without breaking the workflow.**

The `interviewstreet/hiring-agent` repository uses JSON-based caching under the `cache/` directory to speed up resume processing and GitHub API calls during development. When `DEVELOPMENT_MODE` is enabled, the system stores intermediate results in `cache/resumecache_*.json` and `cache/gh_githubcache_*.json` files, but implements defensive error handling to ensure that invalid or corrupted cache files never halt execution.

## Automatic Recovery from Corrupted Cache Files in score.py

The resume processing pipeline in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) implements a defensive loading strategy that treats cache corruption as a recoverable event rather than a fatal error.

### JSON Parsing and Exception Handling

At lines 226-229, the code checks for cache existence before attempting to load it. When `json.loads()` encounters malformed JSON at lines 237-242, the exception is caught immediately:

```python
if DEVELOPMENT_MODE and os.path.exists(cache_filename):
    try:
        cached_data = json.loads(Path(cache_filename).read_text())
        loaded_resume = JSONResume(**cached_data)
        cache_loaded = True
    except Exception as e:
        print(f"⚠️ Warning: Invalid cache file {cache_filename}: {e}")
        print("Ignoring cache and reprocessing PDF...")

```

### Deletion and Fallback Logic

Upon detecting corruption, the system attempts to delete the invalid file using `os.remove()` and falls back to reprocessing the original PDF. If deletion fails due to permission errors (lines 243-247), the code logs the failure but continues execution:

```python
        try:
            os.remove(cache_filename)          # delete corrupt cache

        except Exception as delete_err:
            print(f"Failed to delete invalid cache file {cache_filename}: {delete_err}")

```

## Handling Invalid or Corrupted Cache Files in github.py

The GitHub fetching helper implements similar defensive patterns with additional validation for empty files.

### Empty Cache Validation

In [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 40-42), after parsing JSON, the code explicitly checks if the data is falsy:

```python
        if not cached_data:
            raise ValueError("empty cache")

```

This ensures that empty files trigger the same recovery path as malformed JSON.

### API Cache Recovery Flow

Lines 44-49 handle parsing exceptions, while lines 49-53 manage deletion failures. The warning message follows the same pattern as [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), ensuring consistency across the codebase:

```python
if DEVELOPMENT_MODE and os.path.exists(cache_filename):
    try:
        cached_data = json.loads(Path(cache_filename).read_text())
        if not cached_data:
            raise ValueError("empty cache")
        return 200, cached_data
    except Exception as e:
        print(f"⚠️ Warning: Error reading cache file {cache_filename}: {e}")
        try:
            os.remove(cache_filename)          # delete corrupt cache

        except Exception as delete_err:
            print(f"Failed to delete invalid cache file {cache_filename}: {delete_err}")

```

## Cache File Lifecycle and Safety Mechanisms

The repository excludes the `cache/` directory via `.gitignore`, ensuring fresh environments start without stale data. When invalid or corrupted cache files are detected, the system follows this deterministic sequence:

1. **Detect invalid JSON** via exception handling in `json.loads()`
2. **Log explicit warnings** using the `⚠️ Warning:` prefix to alert developers
3. **Attempt file deletion** with nested `try/except` blocks to handle permission errors
4. **Recompute data** from original sources (PDFs or GitHub API)
5. **Write fresh cache** files upon successful processing

## Summary

- Corrupted cache files in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) trigger automatic recomputation rather than application crashes
- The system attempts to delete invalid files at lines 243-247 and 49-53 but continues execution if deletion fails
- Warnings are logged using the `⚠️ Warning:` prefix to provide visibility during `DEVELOPMENT_MODE`
- Empty caches and malformed JSON are treated identically to missing files via falsy checks
- Original source data (PDFs, GitHub API) remains the authoritative backup for all cached operations

## Frequently Asked Questions

### What error message appears when a cache file is corrupted?

When `json.loads()` fails in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), the system prints: `⚠️ Warning: Invalid cache file {cache_filename}: {e}`. In [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), the message is: `⚠️ Warning: Error reading cache file {cache_filename}: {e}`. Both messages include the specific exception details to aid debugging.

### Does the pipeline stop if it cannot delete a corrupted cache file?

No. Both [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) (lines 243-247) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 49-53) wrap deletion attempts in `try/except` blocks. If `os.remove()` fails due to permissions or other issues, the error is logged with the prefix `Failed to delete invalid cache file` and execution continues with fresh data processing.

### How does the system handle empty cache files?

In [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (lines 40-42), after parsing JSON, the code checks `if not cached_data` and raises a `ValueError("empty cache")`. This triggers the exception handler, treating empty files identically to corrupted ones and forcing a fresh API request.

### Where are cache files stored and when are they created?

Cache files are stored in the `cache/` directory when `DEVELOPMENT_MODE` is enabled. According to the source code, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) creates `resumecache_*.json` files for PDF processing results, while [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) creates `gh_githubcache_*.json` files for GitHub API responses. The `.gitignore` file excludes this directory to prevent stale caches from being committed.