PART 5Connect, operate, and recover5.6
Capacity, input, and execution limits
Limits and input units for attachments, Media, HTML, documents, messages, Asks, Workflows, Project Database, Triggers, waits, Session startup, and lists, with ways to reduce, split, or re-check oversized content.
A Session attachment and a Project Media publication can have different limits even for the same file. Choose the destination and file type before using these tables.
A KiB is 1,024 bytes, a MiB is 1,024 KiB, and a GiB is 1,024 MiB. Byte limits are not character limits: a UTF-8 character can occupy multiple bytes. "Characters" means Unicode characters. These are input and storage constraints, not guarantees of execution time or availability.
Attachments and Project Media
| Target | Limit |
|---|---|
| Attached image | 20 MiB / file |
| Attached PDF | 50 MiB / file |
| Attached video | 200 MiB / file |
| Attachments in one message send | 10 files, 250 MiB combined |
| Attachment availability | 24 hours from the start of upload |
| Project Media image | 20 MiB / file |
| Project Media PDF | 50 MiB / file |
| Project Media video | 2 GiB / file |
| Project Media total per Project | 20 GiB |
| WebUI Media upload | 20 files at a time (unfinished uploads count) |
The 2 GiB Project Media limit is for video only; it does not apply to images or PDFs. Unsupported formats and encrypted PDFs are rejected even when they fit within the size limit. Attachments are not automatically published as Project Media, and a Media canonical URL is not an external public share.
An attachment cannot be used after it expires. In the WebUI composer, each attachment card shows Available until with the expiry time, and an expired attachment blocks sending with An attachment has expired. Attach it again or remove it before sending. The server also rejects expired attachments at send time. Attach the file again, or remove it before sending.
Content limits apply in addition to byte size. For example, a 20-minute MP4 attachment or a 501-page PDF is rejected even if the file is small.
| Target | Content limit |
|---|---|
| Images | 12,000 pixels for width and height, 100,000,000 total pixels, and 64 animation frames |
| PDFs | 500 pages; decompressed PDF streams are also limited to 64 MiB |
| Attached video | 10 minutes |
| Project Media video | 60 minutes |
| All video | 3,840 pixels wide and 2,160 pixels high; this is not an equivalent-area rule for rotated dimensions |
Resize oversized images to the resolution you need, split PDFs to the relevant pages, and adjust video length or bitrate. Do not rename a file extension to bypass format checks. See Media and WebUI attachments.
HTML and Shared Documents
| Target | Limit or format |
|---|---|
| One Project HTML file | 5 MiB (5,242,880 bytes) |
| Project HTML total per Project | 50 MiB and 500 files |
| Project HTML path | Up to 512 bytes for the whole path under html/, 128 bytes per segment, and 8 levels deep. Segments allow only lowercase ASCII letters, digits, ., _, and -, and cannot start with . |
| Share HTML expiry | 1, 7, or 30 days; default 7 |
| Shared Document | 1 MiB |
| Document kind name | Up to 32 characters; starts with a lowercase letter and contains lowercase letters, digits, _, or - |
| Ordinary doc ID | Up to 64 characters; starts with a lowercase letter or digit and contains lowercase letters, digits, _, or - |
| mindmap | 200 nodes |
| brainstorm | 100 ideas; each title up to 50 Unicode code points and each description up to 200 |
An HTML file over 5 MiB is rejected before upload, for that file only, and the reason appears in html/_errors.md. Other HTML files keep syncing, but pages that reference the rejected file may not render correctly. Reduce or split the file and save it again.
Publish finished files such as images and PDFs as Media and reference them from HTML or documents. Base64-embedding a large file in HTML counts against the HTML limit. When a document grows too large, split it into independently readable documents and connect them with WikiLinks.
PROJECT.md and REPORT.md have reserved purposes and uppercase paths. A correct path can still fail to save because of frontmatter syntax or permissions. See Shared Documents, HTML, and Markdown blocks.
Messages, Asks, and Meetings
| Target | Limit |
|---|---|
| Project Chat message body | 100,000 bytes |
| Ask question | 2,000 bytes |
| Ask body | 100,000 bytes |
| Each Ask option | 200 bytes |
| Ask answer text | 32,000 bytes |
| Meeting title | 1–120 characters |
| Meeting participants | Up to 50 names, each 1–120 characters |
| Meeting body | Not whitespace-only; up to 100,000 bytes |
Do not pack long material into an Ask question or options. Put the decision summary and references in the body. A Workflow Decision's rendered body is also subject to the Ask body limit.
Workflows
| Target | Limit or condition |
|---|---|
| One Bundle file | 1 MiB |
| Whole Bundle | 4 MiB and 128 files |
| Relative path inside a Bundle | 1–256 UTF-8 bytes |
| Workflow Steps | 1–64 |
| Direct dependencies of one Step | Up to 32 |
| Dependency edges in a Workflow | Up to 256; cycles are not allowed |
| Rendered Session Step prompt | 100,000 bytes |
| Completion and Run output | 128 KiB and a maximum JSON depth of 32 |
| Attempt feedback body | Non-empty after trimming whitespace, at most 8,192 bytes |
| Run input | 128 KiB and a maximum JSON depth of 32 |
error of a failed completion | Non-empty, at most 4 KiB |
Free text in chat workflow runs | Shortened to 100-character previews marked truncated: true |
| Published Workflow composition | One level. Use a published Workflow from the same owner, or a published Team Workflow addressed as team:<slug> |
The Bundle file limit is separate from the prompt limit after inputs and dependency outputs are rendered. A short template can exceed the runtime limit when it expands a large input. Store long outputs in Project documents and return only small values and references from Step outputs. When a Step's completion would push the Run output over its limit, that Step fails with workflow_completion_limit_exceeded and the Run becomes attention_required. Publish a corrected Revision that stores large artifacts in the Project and returns references, then start a new Run.
Inputs and outputs must match the declared schema. Objects use additionalProperties: false, so select only the required keys when passing one Workflow's output to another. Undeclared keys and type mismatches are rejected even when the size is within limits. See CLI and Workflow reference for syntax.
Project Database
| Target | Limit or condition |
|---|---|
| SQL input and migration file | 100 KiB |
| Query | One SELECT, INSERT, UPDATE, or DELETE statement |
| Query params | JSON array of up to 100 strings, referenced by positional ? |
| Query result | Up to 1,000 rows and 1 MiB of decoded output |
| Migration | Up to 100 statements, with a separate allowlist from queries |
| One WebUI page | 25, 50, or 100 rows |
| Migration ID | 1–128 characters; starts with a lowercase letter or digit and contains lowercase letters, digits, _, or - |
An oversized query result is rejected rather than returned partially. Select the columns and rows you need, using WHERE and an appropriate LIMIT. The 100-parameter limit counts values supplied to placeholders, not rows written.
Live queries do not overlap within one Project. Do not repeatedly send a mutation that is still in progress or whose outcome is unknown; follow the error's read guidance to inspect current state. Build migrations from the parent version in schema.sql, then explicitly apply the synchronized file (Database).
Triggers and scheduled follow-ups
| Target | Condition |
|---|---|
| Project Trigger interval | At least 300 seconds. The end time is optional; if supplied, it cannot precede the start and is inclusive. Without it, the Trigger runs until paused or deleted |
| Scheduled follow-up to an existing Session: delay before the first message | 1 second to 30 days with chat session schedule create --after; the outer aachat session schedule create --at takes a timestamp |
| Scheduled follow-up to an existing Session: repeat interval | 60–86,400 seconds (--repeat-after takes 1 minute to 24 hours; --every takes 60–86,400 seconds), counted from completion of the turn the reservation starts |
| WebUI scheduling inputs | The Session composer's When and a Trigger's Scheduled follow-up take a whole number from 1 to 1,440 minutes. With Repeat on, both use the same number of minutes as the repeat interval |
| Calendar Trigger | IANA timezone, local time, and one or more weekdays (no duplicates); a supplied end date is inclusive |
| Document match | Exact equality on string, number, or boolean frontmatter values in the same Project; multiple conditions are ANDed; fires at most once |
A Trigger starts a fresh Session or Published Workflow. A scheduled follow-up adds a turn to an existing Session. Their interval limits and stop controls differ. Preview time schedules before creating them and check the actual next occurrences. See Triggers for end times and stop controls, and Sessions for creating and cancelling scheduled follow-ups.
Session startup, waits, and workspaces
| Target | Limit or condition |
|---|---|
Startup check in chat session run | Waits up to 40 seconds for the new Session to leave starting, then returns startup |
| Waiting while the agent runtime is not connected | Waiting for the connection has no timeout. An accepted Session remains queued and starts automatically when the runtime connects. |
Targets of chat wait --all | 1–100 (direct child Sessions, top-level Workflow Runs in that Project, and Project Asks) |
| Free space before a Fresh or Workflow Session starts | 20 GiB. If space is short, inactive workspaces of the same agent are reclaimed once; if still short, the Session fails with workspace_capacity_insufficient |
One chat result report submission | 1–50 items and up to 1 MiB of stdin |
startup.state = preparing only means preparation did not finish within 40 seconds; it is not a failure. runtime_offline means that agent's aachat up is not connected. See "A Session does not start" in Troubleshooting.
Search, lists, and text reads
| Target | Limit or default |
|---|---|
Results of query-based message search (Web search, aachat find, and similar) | An excerpt of up to 240 characters around the match; … marks where text was cut |
chat session read --match | Case-insensitive literal search within one Session. Excerpts up to 600 characters; --last defaults to 50, maximum 100. Follow next_page for older matches |
Free text in chat list rows (body, failure reason, and so on) | Truncated to a 100-character preview. Read the full text through the returned detail read (detail_read) |
aachat lists | Default 20 items, maximum 100 (check CLI for per-command defaults) |
chat session list and aachat session list | Default 10 items, maximum 100 |
chat workflow runs | Default 4 items; filter with --state <state> |
Text read with aachat ... --full | 12 KiB (12,288 bytes) per page by default, split on UTF-8 boundaries; --max-bytes allows up to 64 KiB |
Search results are not the full message. To read the full text, jump to the message from the result or use a normal read such as chat read. The first instruction of a Trigger-started Session is excluded from message search (find); read it in that Session's transcript.
Pagination is specific to the surface
| Surface | How to continue |
|---|---|
chat read lists | Read data.items. When data.next_page is a command locator ({kind, program, argv}), run its argv with program as-is. next_page is null on the last page (CLI) |
aachat read lists (project read, project document, session list, session read, ask list, Workflow lists, and the rest) | Run next_page.argv with program as-is; next_page is null on the last page (CLI) |
aachat inbox | Continue the unread Project list with the data.next_page command locator, which includes --before. Read individual Project history with aachat project read |
--full text | Use the returned continuation locator. Offset and checksum detect content that changed between pages |
| Project Database WebUI | Numbered pages with 25 / 50 / 100 rows; changing table or sort changes the query (Database) |
chat inbox / bounded Session decision / matched excerpts | These are bounded views, not a cursor-based full history. Use the suggested history read; chat inbox does not paginate (Sessions, CLI) |
Do not interchange cursors, page numbers, and row limits, or treat the first page as the entire result.
When a limit error appears
First identify the destination, input, or result that exceeded its limit. File size, UTF-8 bytes, a rendered prompt, and decoded SQL output measure different things. Reduce the content or move it into referenced artifacts, then verify the operation's result.
Within these limits, permissions, supported formats, Project status, disk capacity, and provider availability can still prevent an operation. Consult Permissions and Troubleshooting. If an operation's outcome is unknown, establish whether the original request was accepted before submitting changed content as another request.