# Cursor File Size Limit: Codebase Indexing Caps and Large File Workflows

The Cursor file size limit is the threshold beyond which Cursor's AI indexing ignores, truncates, or throws errors when referencing local files in prompts or codebase embeddings. Oversized files are skipped during automated indexing, while inspection tools reject large buffers. This guide outlines Cursor's file boundaries, configuration rules for ignore files, and how remote Fast.io MCP workspaces let developers search large reference corpuses without bloating local repositories.

Source: https://fast.io/resources/cursor-file-size-limit/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-09-11

## How Cursor Enforces Codebase Indexing Limits and File Size Caps

When an automated coding assistant in Cursor attempts to index or edit an oversized file, the editor fails without an actionable warning: background indexing silently ignores the file, inline diffs truncate midway through execution, and the assistant hallucinates class definitions that exist only outside its active memory boundary. Every interaction with an artificial intelligence model in Cursor is bounded by file size thresholds designed to prevent memory exhaustion and runaway token consumption.

The Cursor file size limit is the threshold beyond which Cursor's AI indexing ignores, truncates, or throws errors when referencing local files in prompts or codebase embeddings.

To work effectively within Cursor, software engineers must recognize that the editor applies distinct file size thresholds across different functional subsystems rather than enforcing a single global ceiling:

1. Automated Codebase Indexing. During automatic repository indexing, Cursor computes vector embeddings to power semantic codebase search. Individual large files that surpass the indexing threshold, as well as minified scripts and log files, are automatically skipped by the indexing pipeline. This mechanism ensures that massive data dumps or bundled assets do not consume indexing resources or produce noisy embedding vectors.
2. Direct File Inspection Tools. When an agent invokes internal tools to inspect file contents, such as reading an attached asset or inspecting a test fixture, files that exceed the tool buffer limit throw errors such as "file too large to read."
3. Inline Code Generation and Diff Apply. When applying inline edits through Cursor Composer or inline generation, files with extensive line counts frequently suffer from context degradation. Diff engines struggle to align syntax trees across massive line counts, resulting in partial code replacements, broken braces, or circular edits where the model repeatedly reverts its own modifications.
4. Total Codebase Repository Ceiling. While Cursor does not declare an arbitrary storage cap on repository size, codebases containing extreme file volumes encounter severe performance bottlenecks, long indexing delays, and elevated CPU utilization.

The table below summarizes the operational file size and indexing thresholds enforced within Cursor:

| Operation | Size Threshold | Behavior When Exceeded | Recommended Mitigation |
| :--- | :--- | :--- | :--- |
| Codebase Indexing | 1 MB | File is skipped during embedding generation | Exclude via `.cursorindexingignore` or query via MCP |
| File Read Tools | 2 MB | Tool execution halts with buffer size errors | Split file or filter contents using command-line tools |
| Inline Edit / Apply | 500-1,000 lines | Partial diff application, syntax degradation | Decompose monolithic files into modular components |
| Repository Scope | 100,000 files | Heavy CPU usage, delayed index updates | Apply `.cursorignore` to prune non-essential folders |
| Model Context Window | 128k-200k tokens | Instruction drift, lost-in-the-middle decay | Retrieve targeted excerpts instead of full files |

Cursor extends context window token limits and model tokens on legacy plans through Max Mode billed at the model API rate plus 20%. Modern plans manage context allocation directly through model selection. However, expanding context boundaries does not resolve local file indexing limits, because file size thresholds exist to preserve local IDE responsiveness and embedding quality.

## Why Large Local Files Degrade Agent Reasoning and Inline Edits

Many developers attempt to bypass indexing caps by manually attaching large files to chat prompts using the `@file` mention. If a multi-megabyte database export or a massive generated API client was skipped during background indexing, attaching the entire document directly to the prompt appears to be a logical solution. In practice, this approach triggers severe reasoning degradation known as attention attenuation.

Modern transformer models process tokens non-uniformly across long prompts. In what researchers term the lost-in-the-middle effect, models allocate high attention weights to tokens at the very beginning of the prompt (where system instructions and tool definitions reside) and tokens at the very end (the immediate user instruction). Tokens located in the middle of a massive context payload receive substantially lower attention weights. When an engineer attaches a multi-megabyte reference document, that file consumes tens of thousands of tokens, pushing core architectural rules and type definitions into the neglected middle zone.

This dynamic produces four common failure modes during development sessions:

* Hallucinated Function Signatures. When interface contracts or schema definitions sit in the middle of a bloated prompt, the model loses track of parameter names, optional fields, and return types, generating code that fails type checking.
* Circular Refactoring Loops. During multi-file edits, an agent modifies a function in file A, which breaks an unindexed dependency in file B. When prompted to fix file B, it reverts the change in file A because it cannot maintain global awareness across both files simultaneously.
* Truncated Inline Diffs. When an agent attempts to rewrite a file exceeding 1,000 lines, the diff generator often runs out of output tokens before completing the patch. The editor applies only the first half of the modification, leaving the target file with missing functions or unclosed brackets.
* High Token Consumption and Latency. Uploading multi-megabyte payloads on every chat turn consumes hundreds of thousands of tokens per prompt, introducing significant response latency and rapidly depleting monthly model allowances.

This issue mirrors the challenge developers encountered in Claude Projects, where a strict project limit of 50 files forced engineers to prune reference documentation manually. When teams migrate from web-based assistants to Cursor to escape file count constraints, they often repeat the same mistake by committing large reference documents directly into their local Git repository. Local repositories were built for source code, not for massive documentation libraries, dataset samples, or specification archives.

## How to Configure Local Exclusions with .cursorignore and .cursorindexingignore

To prevent large files from crashing the local indexer or degrading editor performance, Cursor provides two configuration files: `.cursorignore` and `.cursorindexingignore`. Both files use standard `.gitignore` pattern syntax, but they govern different layers of the editor's AI toolset.

Understanding the operational distinction between these two files is critical:

* `.cursorignore` acts as a strict blocklist across the entire AI subsystem. Any file or directory matched by `.cursorignore` is hidden from codebase indexing, Cursor Tab autocomplete, inline edits, and agent tools. Even if a developer types `@filename` in chat, Cursor blocks the model from reading the contents.
* `.cursorindexingignore` restricts only semantic vector indexing. Files matching patterns in this file are skipped when Cursor computes repository embeddings, preventing indexing bloat. However, developers and agents can still explicitly reference these files in chat or Composer when needed.

To configure these exclusions, create the respective file in the root directory of your project. For example, a project `.cursorignore` file excludes dependencies, build outputs, database snapshots, logs, and sensitive environment configs:

```text
node_modules/
dist/
build/
.next/

*.sql
*.sqlite
data/dumps/
fixtures/large_dataset.json

*.log
coverage/
*.min.js
*.min.css

.env
.env.*
!.env.example
```

If your repository contains files that you want available for occasional `@file` mentions but excluded from background embedding calculations, define them in `.cursorindexingignore` instead:

```text
docs/openapi-full-spec.json
schemas/database-schema.sql
docs/generated-reference/
```

For engineering teams managing large monorepos with nested packages, Cursor supports hierarchical ignore rules. Within the Cursor settings under the indexing configuration section, you can enable hierarchical ignore searching. When enabled, Cursor inspects subdirectories for local `.cursorignore` files and applies rules relative to each package root.

While ignore files succeed at keeping local indexing performant, they reveal a major limitation in standard developer workflows. The standard advice across developer forums is simply to add large files to `.cursorignore`. However, when you exclude an OpenAPI specification, a database schema, or architectural documentation from Cursor, the AI assistant becomes incapable of referencing that knowledge when generating application code. Ignoring the file solves the indexing bottleneck by destroying the context your agent needs.

## How to Offload Large Reference Corpuses to Fast.io Remote MCP Workspaces

The sustainable architecture for handling large documentation corpuses and reference datasets is moving them out of local Git folders and into an intelligent cloud workspace. Instead of forcing Cursor to parse multi-megabyte files on developer laptops, teams store their reference materials in a Fast.io workspace.

Fast.io provides shared org-owned workspaces equipped with per-file version history, granular permissions, an append-only audit log, and native Intelligence Mode. You can populate a workspace by uploading files directly, or sync reference documents from Dropbox, Box or OneDrive. Google Drive imports today with sync coming soon, enabling teams to aggregate technical documentation, API specifications, and architectural diagrams without local file management overhead.

When Intelligence Mode is enabled on a Fast.io workspace, every document is automatically indexed for hybrid search, combining full-text keyword indexing with semantic vector retrieval. Rather than attaching whole files to Cursor prompts or fighting local indexing limits, the coding agent connects to Fastio through the Model Context Protocol (MCP) and retrieves only the exact paragraphs relevant to the current task.

Cursor connects to remote MCP servers using Streamable HTTP. To register your Fast.io workspace, create or update `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "fastio-workspace": {
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      }
    }
  }
}
```

The endpoint is also accessible via legacy SSE transport at `https://mcp.fast.io/sse`. Complete tool documentation is available at `https://mcp.fast.io/skill.md`, and architectural integration patterns are detailed on the [Fast.io for Agents](/storage-for-agents/) page.

Connecting Cursor to Fast.io provides distinct operational advantages over maintaining local reference files:

* Zero Local Disk Bloat. Multi-gigabyte documentation archives and sample datasets reside in cloud storage rather than inflating local Git repositories or developer SSDs.
* Bypassing Local Indexing Caps. Fastio performs semantic chunking and indexing on cloud infrastructure, completely removing local indexing bottlenecks from your development workflow.
* Targeted Context Injection. When an agent needs information about an authentication protocol or API parameter, it issues a targeted search query through MCP. The workspace returns only the relevant excerpts, keeping prompt token consumption minimal and eliminating attention degradation.
* Centralized Team Reference. In team environments using Cursor Teams subscription plans, where Premium seats add 5x the Standard limits on Agent models, team members share a unified, pre-indexed knowledge base rather than re-indexing identical assets locally across separate workstations.

Connecting an external MCP workspace does not alter Cursor's internal model token limit or change the vendor's hard software caps. What changes is the retrieval mechanism: instead of pasting an entire monolithic technical manual into a prompt, the agent searches the remote index and pulls only the specific paragraphs containing the necessary interface contract.

## Structuring Complex Reference Context with Metadata Views

Technical reference corpuses frequently consist of complex, semi-structured documents: vendor API specifications, regulatory security standards, database table definitions, and client contract terms. While vector search identifies general text passages, coding agents often require precise, structured parameters such as field data types, HTTP route paths, query parameters, and deprecation schedules.

To solve this requirement, Fast.io provides [Metadata Views](/product/document-data-extraction/). Metadata Views transform unstructured files into a live, queryable database. Users define the fields they need extracted in natural language, and Fast.io generates a typed schema supporting text, integer, decimal, boolean, URL, JSON, and date values. The platform scans documents across the workspace and populates a filterable spreadsheet without requiring custom parsing scripts or OCR templates.

Because Fast.io exposes Metadata Views directly through MCP, Cursor agents can execute structured queries instead of scanning prose:

```json
{
  "tool": "fastio_query_metadata_view",
  "arguments": {
    "view_name": "API_Route_Registry",
    "filter": "status == 'Active' && module == 'Billing'"
  }
}
```

The agent receives a clean, compact JSON response containing the exact route parameters and authentication headers needed to construct an API client. Developers can add new columns to a view at any time without reprocessing files.

Beyond structured data extraction, Fast.io provides the operational foundation required for reliable human-agent collaboration:

* Per-File Version History. Every update performed by a human engineer or an automated agent is tracked as a distinct version. If an agent writes an invalid configuration or alters a shared specification unexpectedly, developers can inspect diffs and restore earlier revisions immediately.
* Append-Only Audit Log. All read, write, search, and export actions are recorded with timestamps and identity attribution, providing full visibility into autonomous agent activity.
* Collaborative Notes. Real-time co-editing allows developers and AI assistants to draft architecture decision records, API design notes, and deployment runbooks within the same shared document.
* Scoped Ownership Transfer. Development agencies and contractors can build organizations and workspaces on behalf of clients, configure permissions and MCP connections, and transfer organizational ownership to the client upon project completion while retaining administrative access.

Adopting Fast.io is straightforward. Every organization starts with a 14-day free trial, which requires a credit card. | Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo, providing development teams with persistent cloud workspaces, automated intelligence, and remote MCP connectivity. You can review plan options on the [pricing page](/pricing/).

## Frequently asked questions

### What is the maximum file size Cursor can index?

Cursor automatically skips individual files that exceed the single-megabyte threshold during its background codebase indexing process. This threshold prevents massive data dumps, minified assets, and build artifacts from overwhelming the local vector embedding pipeline and degrading IDE performance.

### How do I fix the 'File too large' error in Cursor?

The 'File too large' error typically occurs when an agent tool attempts to read an oversized file exceeding tool buffer limits, or when a file exceeds the line buffer during inline editing. You can resolve this by adding the file to `.cursorignore`, splitting the file into smaller modular files, or offloading the file to an external Fastio workspace accessible via remote MCP.

### How can Cursor access large datasets without indexing the whole file?

Instead of storing large datasets locally in your repository, upload them to a Fast.io workspace with Intelligence Mode enabled. Fast.io indexes the files on cloud infrastructure. Connect Cursor to the workspace using the remote MCP server at `https://mcp.fast.io/mcp/key`, allowing the assistant to perform semantic search and retrieve only relevant excerpts on demand.

### What is the difference between .cursorignore and .cursorindexingignore?

The `.cursorignore` file acts as a complete blocklist that hides files from codebase indexing, Tab autocomplete, inline edits, and agent tools. In contrast, `.cursorindexingignore` only excludes files from semantic vector indexing, allowing developers and agents to still reference the files explicitly in chat prompts.

### Why do files with excessive line counts fail during inline edits?

Large files with excessive line counts frequently cause context degradation during inline diff generation. Diff algorithms struggle to maintain syntactic alignment across long line ranges, leading to truncated patches, broken code syntax, and circular editing loops where the model repeatedly reverts its own edits.

### Does connecting Fast.io via MCP raise Cursor's local file size limit?

No. Connecting Fast.io does not alter Cursor's internal software limits or change model token boundaries. Instead, it offloads storage and retrieval to an external intelligent workspace, allowing Cursor to search indexed documents remotely and ingest small, focused excerpts rather than processing multi-megabyte files locally.

## Sources

- [Cursor: Models & Pricing](https://cursor.com/docs/models-and-pricing) — Cursor extends context window token limits and model tokens on legacy plans through Max Mode billed at the model API rate plus 20%.
- [Cursor: Models & Pricing](https://cursor.com/docs/models-and-pricing) — Cursor Teams subscription plans offer a Premium seat that adds 5x the Standard limits on Agent models.

Editorial standards: https://fast.io/editorial-policy/

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.