CertSafari
    Snowflake SnowPro Specialty: Gen AI (GES-C02)· Lessons

    Domain 4 · Lesson 15/15

    Troubleshooting and optimizing Snowflake document processing

    Troubleshoot and optimize document processing.

    18 min read
    3.75% of exam
    5 sources
    Published 21 Oct 2026
    Docs as of 4 Oct 2026

    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.

    A successful AI_EXTRACT result: error is null and the extracted values are under responsejson
    {
      "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"
      }
    }

    Checkpoint 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?

    Sources12

    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.

    Generating a one-hour pre-signed URL for a staged filesql
    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?

    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?

    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?

    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.

    AI_PARSE_DOCUMENT error messages and what to check
    Message beginsCauseWhat to check
    Maximum number of 2000 pages exceeded.Document over the 2,000-page limitSplit the file, or parse only the page ranges you need
    Maximum file size of 104857600 bytes exceeded.File larger than 100 MBCompress or split the file before staging it
    Page size in pixels exceeds 10000x10000.Image or converted page too largeResample the image or reduce the page dimensions
    The provided file format .bin isn't supported.File read as a binaryConfirm the extension and that the stage uses server-side encryption
    Document contains language that is not supported.Language outside the trained setConfirm the document language is supported
    Provided file cannot be accessed.Insufficient privilegesStage privileges and the CORTEX_USER role
    The Parse Document function did not respond in the allowed time.TimeoutRetry

    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.

    Sources45

    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.

    How AI_PARSE_DOCUMENT counts billable pages
    File typeWhat is billed as one page
    PDF, DOCXEach page of the document
    JPEG, JPG, TIF, TIFF, PNGEach image file
    HTML, TXTEach 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.

    Sources14

    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.

    Limits on an arctic-extract fine-tuning job
    ConstraintValue
    Recommended minimum documentsAt least 20
    Unique document files in the DatasetAt most 1,000 (the same file can be referenced more than once)
    Unique questions100 for entity extraction, 10 for table extraction
    Questions × total pages50,000 or less
    Pages per document64 in AWS US West 2 and Europe Central 1; 125 in AWS US East 1 and Azure East US 2
    File formatsPDF, PNG, JPG, JPEG, TIFF, TIF
    Unsupported setupsClient-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.

    Creating a fine-tuning job from versioned training and validation Datasets, with a fixed epoch countsql
    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.

    Running inference with the fine-tuned modelsql
    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')
    );

    Checkpoint 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?

    Sources5

    Sources

    (5)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 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. 2.
      “The model for table extraction returns answers that are up to 4096 tokens long.”
      ↩︎ Reading the error field on each document
    3. 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. 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. 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

    Ready to test yourself?

    Practise the 13 questions on this subdomain.

    Spotted a mistake, or was something unclear? Tell us.