What you will be able to do
- Find failed documents by reading the error field that AI_EXTRACT returns, and match each error message to its cause
- Use GET_PRESIGNED_URL to open a staged source file, and know what the function does and does not check
- Tell privilege failures apart from failures caused by document limits, and know which stage privilege each check needs
- Keep document jobs cheap by using a small warehouse and limiting pages, questions and scale_factor
- Decide when to fine-tune arctic-extract, and prepare a valid training Dataset
Key concept
Per-document error output — AI_EXTRACT returns one JSON object for each document it processes. The object has an error key next to the response key, so troubleshooting starts by finding the rows where error is not null and reading the message.
1.Reading the error field on each document
A document job that runs over a whole stage seldom fails all at once. Usually a few files out of hundreds come back empty. AI_EXTRACT handles this by returning an object for every document, with an error key next to the response key. For a document that worked, error is null and response holds the extracted entities, lists or tables. For a document that failed, error holds a message. So the first diagnostic step is to filter the results for rows where error is not null and group them by message.
{
"error": null,
"response": {
"title": "Financial report"
}
}The messages fall into a few groups, and each group needs a different fix. Retry Internal error., which is a system error: wait and try again, and contact Snowflake support if it continues. Fix the file for Not found. or Provided file cannot be found. (the path points at nothing), The provided file isn't in the expected format or is corrupted., and the size limits such as Maximum number of 125 pages exceeded. Fix the query for Missing or empty response format., Invalid response format. (not valid JSON), Duplicate feature name found, and Too many questions, which means the question count is over the allowed limit. Fix access for Provided file cannot be accessed., which means the current user lacks the privileges to read the file. Retrying any of the last three groups unchanged gives the same error again.
Some failures show up in the response, not in the error field. If a value has typos or character-level OCR errors, or the document has small text, dense layouts or pages larger than A4, the config object's scale_factor setting (1.0 to 4.0) scales pages up before the model reads them. If a table comes back cut short, the cause is the table-extraction model's 4,096-token answer limit. The fix is to split a multi-page table into one-page documents and join the results afterwards, or to extract a dense table as two sets of columns.
Checkpoint 1 of 9· Fill the gap
This is the result AI_EXTRACT returns for a document it processed successfully. Your triage query keeps only the rows where the error key is not this value. Which value fills the blank?
{
"error": ? ,
"response": {
"title": "Financial report"
}
}Each document gets its own object. On a success, error is null and the extracted values are under response. So to find the failed documents, filter for rows where error is not null and read the message.
Source: docs.snowflake.comCheckpoint 2 of 9· Check yourself
A nightly AI_EXTRACT job over 2,000 invoices returns 40 rows with a non-null error. You want to retry some of them automatically and unchanged. Which error message is worth retrying that way?
Internal error. is a system error, so you wait and try again. The other three need a fix first: privileges for the access error, the query for too many questions, and the file for the page limit. Retrying them unchanged returns the same error.
“Internal error. | System error occurred. Wait and try again.”Source: docs.snowflake.com
2.Opening the source file with GET_PRESIGNED_URL
Once you know which document failed, you often need to look at it. GET_PRESIGNED_URL takes a stage name and a path relative to that stage, and returns a URL with a short-lived access token. You can open the URL in a browser, click it in a Snowsight results table, or send it to the REST API for file support. A scan that turns out to be sideways, blank or 400 pages long becomes obvious in seconds.
SELECT GET_PRESIGNED_URL(@images_stage, 'us/yosemite/half_dome.jpg', 3600);GET_PRESIGNED_URL does not check that the file exists. It signs whatever path it is given. If a cleanup task removes a file between the URL call and the next pipeline step, the URL call still succeeds and the next step fails when it fetches the URL. In a browser, a missing file shows a NoSuchKey error in XML. That is why the way to confirm a URL is to open it, and why a successful GET_PRESIGNED_URL call does not prove the file is still there.
A few other rules cause failures that look similar. Expiration defaults to 3,600 seconds. The maximum is 604,800 seconds (seven days), except on stages that connect to S3 through an AWS IAM role and on Microsoft Fabric OneLake stages, where it is 3,600. Asking for more than the maximum returns an error; it does not fail silently. The stage needs server-side encryption, so if files downloaded from an internal stage come out corrupted, ask the stage creator to confirm ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE'). On Azure, the function works only when the container is accessed through a storage integration, not through a SAS token you generate. The function works on internal and external stages alike.
Checkpoint 3 of 9· Check yourself
To check a failed invoice, you run GET_PRESIGNED_URL on an internal stage of scanned invoices. Your role has USAGE on that stage, but the function returns no value for it. Which grant on the stage fixes this?
The privilege GET_PRESIGNED_URL needs depends on the stage type. USAGE works only for an external stage, and an internal stage needs READ. OWNERSHIP is not required, and SELECT is not a stage privilege.
“This SQL function returns a value for any role that has the following privilege on the stage: External stage:USAGEInternal stage:READ”Source: docs.snowflake.com
Checkpoint 4 of 9· Exam question
A pipeline step calls GET_PRESIGNED_URL against a file that a separate process deletes from an internal stage moments earlier, then hands the returned URL to a document-extraction step. The GET_PRESIGNED_URL call itself succeeds and returns a URL, but the subsequent fetch of that URL fails. What is the most likely explanation?
Correct answer: A — GET_PRESIGNED_URL generates a URL without checking whether the target file currently exists, so the fetch failed only once the deleted file was actually accessed
- A. GET_PRESIGNED_URL builds the URL from the stage and path arguments without verifying the object is present, so a URL is returned even for a file that no longer exists. The failure only surfaces later, when something actually tries to fetch content from that URL and gets a not-found style error.
- B. Missing server-side encryption would prevent the function from generating a URL at all, not cause a delayed fetch failure after a valid URL was already returned. Since the call to GET_PRESIGNED_URL succeeded, encryption was already correctly configured on the stage.
- C. An expiration value that exceeds the stage's maximum lifetime is capped or rejected at the time the URL is generated, not after a successful call. Because the URL was returned successfully, the expiration value was already within bounds.
- D. Presigned URLs can be generated for files in internal stages, and internal stages are commonly used with document-extraction workflows. This option describes a blanket restriction that does not reflect how internal stages are actually supported.
Checkpoint 5 of 9· Exam question
A pipeline calls GET_PRESIGNED_URL against files sitting in two different stages: one internal stage and one external stage on cloud storage. Which privilege must the calling role hold on each stage type?
Correct answer: A — READ on the internal stage and USAGE on the external stage
- A. Internal stages require the READ privilege for GET_PRESIGNED_URL, while external stages require the USAGE privilege. This pairing is correct and matches the documented privilege model for the function.
- B. This reverses the actual requirement: USAGE is what external stages need, and READ is what internal stages need, not the other way around. Applying this pairing would leave the role under-privileged on the internal stage.
- C. OWNERSHIP is a much broader grant than the function requires and is not the documented minimum privilege for either stage type. Requiring OWNERSHIP everywhere would over-provision access well beyond what GET_PRESIGNED_URL needs.
- D. SELECT is a table-level privilege and is not meaningful on a stage object, so it cannot satisfy the internal-stage requirement. The function's documented privilege model does not reference SELECT at all.
Sources3
3.Requirements and privileges as causes of failure
Most persistent document errors come from one of two causes. Either the document breaks a limit, or the caller lacks access. The limits on format, size, page count and resolution are covered in Document requirements: formats, file size, page count and resolution. What matters here is spotting them in an error, because each message names the limit it hit and the actual value, such as page count, pixels or bytes. AI_PARSE_DOCUMENT has its own messages, and the table below maps them to what to check.
| Message begins | Cause | What to check |
|---|---|---|
| Maximum number of 2000 pages exceeded. | Document over the 2,000-page limit | Split the file, or parse only the page ranges you need |
| Maximum file size of 104857600 bytes exceeded. | File larger than 100 MB | Compress or split the file before staging it |
| Page size in pixels exceeds 10000x10000. | Image or converted page too large | Resample the image or reduce the page dimensions |
| The provided file format .bin isn't supported. | File read as a binary | Confirm the extension and that the stage uses server-side encryption |
| Document contains language that is not supported. | Language outside the trained set | Confirm the document language is supported |
| Provided file cannot be accessed. | Insufficient privileges | Stage privileges and the CORTEX_USER role |
| The Parse Document function did not respond in the allowed time. | Timeout | Retry |
A permission-denied failure has a different signature from a limit failure. The message names no limit and no measured value. It says the file cannot be accessed, and it repeats for every file the role touches on that stage. The full grant set is covered in Privileges and compute for running AI functions on staged files. For diagnosis, check two layers. First, the caller needs the SNOWFLAKE.CORTEX_USER database role, which a user with ACCOUNTADMIN must grant. Second, the role needs access to the stage that holds the file. Every function in the chain has its own requirements: a role that can run AI_EXTRACT can still fail to generate pre-signed URLs if it holds USAGE on an internal stage when that stage needs READ.
Encryption is a less obvious requirement that differs between functions. AI_EXTRACT reads files from stages with client-side or server-side encryption. GET_PRESIGNED_URL needs server-side encryption. Fine-tuning arctic-extract does not support client-side encrypted stages at all. So a stage that works for inference can still fail when the same files are reused for training or for review links.
Checkpoint 6 of 9· Match them up
An AI_PARSE_DOCUMENT run over a stage returns several different error messages. Pair each message with the first thing you should check or do.
Tap a term, then the definition that fits it.
Limit errors name the limit they hit, so you fix the file. The .bin error means the file was read as a binary, which can point to stage encryption. The access error names no limit because it is about privileges. The timeout is the only one here that is worth retrying unchanged.
“Provided file cannot be accessed. | The file can’t be accessed due to insufficient privileges.”Source: docs.snowflake.com
4.Keeping document jobs fast and cheap
Warehouse size is the wrong lever for speed. The document model does the heavy work, and AI_EXTRACT already scales by processing several documents at the same time. Snowflake recommends a warehouse no larger than MEDIUM for both AI_EXTRACT and AI_PARSE_DOCUMENT. A bigger warehouse adds credits without making the job any faster.
The real cost drivers are pages, questions and tokens. Token billing in general is covered in What counts as a billable token for AI functions. For documents specifically, AI_EXTRACT counts each page of a PDF, DOCX or TIFF, and each JPEG or PNG image, as 970 tokens. It then adds the prompt tokens from your questions and the output tokens it returns. Increasing scale_factor raises input tokens in proportion and divides the maximum page count by the same factor. At 4.0, a page costs 3,880 tokens and a document can have at most 31 pages. Use scale_factor only on the documents whose OCR actually needs it, not as a default for every call.
| File type | What is billed as one page |
|---|---|
| PDF, DOCX | Each page of the document |
| JPEG, JPG, TIF, TIFF, PNG | Each image file |
| HTML, TXT | Each 3,000-character chunk, including a shorter final chunk |
Because billing is per page, the cheapest page is the one you never send. AI_PARSE_DOCUMENT can filter by page range. If the information you need is always on the first two pages of a 40-page contract, parsing only those pages cuts that part of the cost by 95%. With AI_EXTRACT, ask only the questions you will use, one value per question, and send several questions in one call instead of calling once per question. Every extra call adds the same per-page tokens again. Ask specific questions: "What is the date?" on a document with an issue date and a signature date wastes tokens on an answer you cannot trust.
Checkpoint 7 of 9· Match them up
You are estimating the cost of an AI_PARSE_DOCUMENT job over a mixed stage before it runs. Match each file type to what Snowflake bills as one page.
Tap a term, then the definition that fits it.
AI_PARSE_DOCUMENT bills by pages processed, and what counts as a page depends on the format. Paged formats bill per page, images bill per file, and text formats bill per 3,000-character chunk, so even a short final chunk counts as a full page.
“For HTML and TXT files, each chunk of 3,000 characters is billed as a page, including the last chunk”Source: docs.snowflake.com
5.Fine-tuning arctic-extract when accuracy is too low
Fine-tuning is the fix to try after better questions, a better response format and scale_factor have all failed to improve accuracy. The general mechanism is covered in Cortex Fine-tuning. For documents, you train arctic-extract on your own files and expected answers, then pass the tuned model to AI_EXTRACT. It helps most on a document type with a recurring layout the base model keeps misreading, such as a supplier's invoice format or an in-house payslip.
The training data is a Snowflake Dataset with three required columns. The column names are case-insensitive, can appear in any order, and any extra columns are ignored. File holds a stage path to the document. Prompt holds the questions in any format AI_EXTRACT's responseFormat accepts. Response holds the expected answers, with keys that match the Prompt keys. If a document does not contain an answer, set its response to None. Include rows even for questions the base model already answers correctly, because that confirms those answers. The tuned model's schema is the set of all unique questions in the Dataset.
| Constraint | Value |
|---|---|
| Recommended minimum documents | At least 20 |
| Unique document files in the Dataset | At most 1,000 (the same file can be referenced more than once) |
| Unique questions | 100 for entity extraction, 10 for table extraction |
| Questions × total pages | 50,000 or less |
| Pages per document | 64 in AWS US West 2 and Europe Central 1; 125 in AWS US East 1 and Azure East US 2 |
| File formats | PDF, PNG, JPG, JPEG, TIFF, TIF |
| Unsupported setups | Client-side encrypted stages; custom network policies |
The 20-document minimum is about how many distinct examples the model sees. Eight invoices referenced several times each are still eight invoices. A team with only eight should collect more real examples before starting a job. The questions × pages cap trades off the other way: 10 questions across 5,000 pages is valid, and so is 100 questions across 500 pages.
SELECT SNOWFLAKE.CORTEX.FINETUNE(
'CREATE',
'@database.schema.model_name',
'arctic-extract',
'snow://dataset/training_ds/versions/2',
'snow://dataset/validation_ds/versions/4',
'{"max_epochs": 3}'
);max_epochs takes a value from 2 to 10. If you leave it out, the system chooses. Creating the job needs the CORTEX_USER database role and several object privileges: USAGE or OWNERSHIP on the database and schema that hold the Dataset, READ or OWNERSHIP on the stage that holds the documents, and CREATE MODEL on the schema that will store the model. FINETUNE('DESCRIBE') reports the job's status, progress, trained_tokens, and training and validation loss. Once the job finishes, a role with OWNERSHIP, USAGE and READ on the model passes it through AI_EXTRACT's model argument. You can still use responseFormat to override the trained questions.
SELECT AI_EXTRACT(
model => 'db.schema.my_tuned_model',
file => TO_FILE('@db.schema.files','document.pdf')
);Checkpoint 8 of 9· Fill the gap
Your arctic-extract fine-tuning job has finished, and your role holds OWNERSHIP, USAGE and READ on the new model. Which named argument makes AI_EXTRACT use the tuned model instead of the base model?
SELECT AI_EXTRACT(
? => 'db.schema.my_tuned_model',
file => TO_FILE('@db.schema.files','document.pdf')
);You pass a fine-tuned arctic-extract model to AI_EXTRACT through the model argument. You don't need responseFormat because the model already knows the questions it was trained on. responseFormat only overrides those questions, and config holds settings such as scale_factor.
Source: docs.snowflake.comCheckpoint 9 of 9· Exam question
A document team wants to fine-tune an arctic-extract model so it better recognizes their company's invoice layout, but they currently have only 8 sample invoices available. Following Snowflake's guidance, what should they do before starting the fine-tuning job?
Correct answer: A — Gather additional invoices until reaching Snowflake's recommended minimum of roughly 20 documents, since fine-tuning quality depends on enough representative training examples
- A. Snowflake recommends using at least around 20 documents when fine-tuning arctic-extract models, since too few examples limits how well the model generalizes to layout variation. Expanding the sample set before training is the documented, supported path.
- B. Snowflake does publish a recommended minimum document count for fine-tuning, so this claim of no minimum requirement is incorrect. Training on far fewer documents than recommended risks a poorly adapted model.
- C. Duplicating the same handful of invoices adds rows without adding new layout variation, so it does not address the underlying lack of representative training data. The model would still only have seen 8 distinct documents.
- D. Combining files into one PDF reduces rather than increases the number of distinct training documents available to the model. Question count does not substitute for having a sufficiently diverse set of source documents.
Sources5
Sources
(5)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“The current user does not have sufficient privileges to access the file.”
↩︎ Reading the error field on each document“A system error occurred. Wait and try again. If the error persists, contact Snowflake support.”
↩︎ Reading the error field on each document“Extracted text contains typos or character-level OCR errors”
↩︎ Reading the error field on each document“For paged file formats (PDF, DOCX, TIF, TIFF), each page is counted as 970 tokens.”
↩︎ Keeping document jobs fast and cheap“The number of input tokens consumed increases proportionally with scale_factor.”
↩︎ Keeping document jobs fast and cheap“A JSON object containing the extracted information. The structure of the response depends on the type of extraction.”
↩︎ Key concept - 2.
“The model for table extraction returns answers that are up to 4096 tokens long.”
↩︎ Reading the error field on each document - 3.
“This SQL function generates a pre-signed URL for the file path that you specify, even if the file does not exist on the stage.”
↩︎ Opening the source file with GET_PRESIGNED_URL“Otherwise, the maximum expiration time is 604800 (7 days).”
↩︎ Opening the source file with GET_PRESIGNED_URL“Server-side encryption is required on the internal or external stage.”
↩︎ Opening the source file with GET_PRESIGNED_URL“If you specify a longer expiration time, the function returns an error.”
↩︎ Opening the source file with GET_PRESIGNED_URL“If the file does not exist, the browser returns a NoSuchKey error in XML format.”
↩︎ Exam trap 1“This SQL function returns a value for any role that has the following privilege on the stage: External stage:USAGEInternal stage:READ”
↩︎ Exam trap 2“This SQL function returns a value for any role that has the following privilege on the stage: External stage:USAGEInternal stage:READ”
↩︎ Checkpoint - 4.
“a user with the ACCOUNTADMIN role must grant the SNOWFLAKE.CORTEX_USER database role to the user who will call the function.”
↩︎ Requirements and privileges as causes of failure“Maximum number of 2000 pages exceeded. The document has {actual_pages} pages.”
↩︎ Requirements and privileges as causes of failure“in a smaller warehouse (no larger than MEDIUM)”
↩︎ Keeping document jobs fast and cheap“For HTML and TXT files, each chunk of 3,000 characters is billed as a page”
↩︎ Keeping document jobs fast and cheap“Larger warehouses do not increase performance.”
↩︎ Exam trap 3“Internal error. | System error occurred. Wait and try again.”
↩︎ Checkpoint“Provided file cannot be accessed. | The file can’t be accessed due to insufficient privileges.”
↩︎ Checkpoint“Larger warehouses do not increase performance.”
↩︎ Prediction“For HTML and TXT files, each chunk of 3,000 characters is billed as a page, including the last chunk”
↩︎ Checkpoint - 5.
“Client-side encrypted stages are not supported.”
↩︎ Requirements and privileges as causes of failure“Snowflake recommends using at least 20 documents for fine-tuning.”
↩︎ Fine-tuning arctic-extract when accuracy is too low“Number of questions multiplied by total number of pages in all document files in the Dataset must be equal or less than 50,000.”
↩︎ Fine-tuning arctic-extract when accuracy is too low“set the response to None if the document does not contain an answer to the question.”
↩︎ Fine-tuning arctic-extract when accuracy is too low“Fine-tuning arctic-extract models is currently incompatible with custom network policies.”
↩︎ Fine-tuning arctic-extract when accuracy is too low“Snowflake recommends using at least 20 documents for fine-tuning.”
↩︎ Exam trap 4