Skip to content
EntryLayer Operational data entry for Snowflake

SQL API Errors & Troubleshooting

Use this page when a SQL API call returns status = error, when Cortex cannot complete an admin workflow, or when source metadata access fails.

ERRORS

Section titled “ERRORS”

Error codes:

ERR_INVALID_INPUT: required input is missing or malformed.

ERR_VALIDATION: input shape is syntactically valid JSON but violates a field-level contract.

ERR_INVALID_SOURCE_OBJECT: source_object is not an unquoted DB.SCHEMA.OBJECT name.

ERR_SOURCE_DESCRIBE_FAILED: source object could not be described with the caller grants available to the app.

ERR_SOURCE_HAS_NO_COLUMNS: source object metadata returned no columns.

ERR_SOURCE_METADATA_REQUIRED: CREATE_PROJECT was called without source metadata from the restricted-caller helper.

ERR_SOURCE_QUERY_FAILED: a caller-governed source data query failed, for example LIST_FIELD_DISTINCT_VALUES, QUERY_SUBMISSION_GRID, QUERY_RELATIONSHIP_SUBMISSION_GRID, GET_VIRTUAL_SUBMISSION, GET_VIRTUAL_SUBMISSION_BREADCRUMB, or MATERIALIZE_VIRTUAL_SUBMISSION could not read the planned source columns.

ERR_SOURCE_ROW_NOT_FOUND: the exact source row was not found or was not visible under the caller grants.

ERR_SOURCE_MASKING_DESCRIBE_FAILED: source masking metadata could not be verified before returning a source-backed virtual row.

ERR_CALLER_CONTEXT_REQUIRED: a source-backed submission or virtual-row operation requires caller-governed source-row access that is not available to the service RPC.

ERR_FORBIDDEN: caller does not have an EntryLayer admin seat or the required project permission.

ERR_NOT_FOUND: requested EntryLayer project or resource was not found.

ERR_CONFLICT: requested change conflicts with current state.

ERR_NOT_CONFIGURED: EntryLayer organization setup is incomplete.

ERR_SQL_API_RPC_UNAVAILABLE: internal service function call failed.

ERR_UNKNOWN_COMMAND: internal RPC command is not recognized.

ERR_INTERNAL: unexpected SQL API service error.

TROUBLESHOOTING

Section titled “TROUBLESHOOTING”

Troubleshooting:

If CALL fails with a Snowflake privilege error before returning an envelope:

  • Grant the app admin application role: GRANT APPLICATION ROLE ENTRYLAYER.ENTRYLAYER_ADMIN TO ROLE MY_ROLE;

ERR_SOURCE_DESCRIBE_FAILED:

  • The app could not DESCRIBE the source object through restricted caller rights.
  • Check DB.SCHEMA.OBJECT spelling, use unquoted identifiers, grant caller USAGE on database/schema, and grant inherited caller REFERENCES for metadata and SELECT for source-row operations on source tables. For semantic views, also verify DESCRIBE SEMANTIC VIEW succeeds for the caller.
  • Rerun VALIDATE_SOURCE after fixing grants.

ERR_INVALID_SOURCE_OBJECT:

  • source_object must be an unquoted three-part name: DB.SCHEMA.OBJECT.

ERR_FORBIDDEN:

  • The caller reached the API but does not have an EntryLayer admin seat/membership. Complete app admin setup or assign the caller an admin license/seat.

ERR_NOT_CONFIGURED:

  • Open the EntryLayer app UI and complete initial organization setup before using the SQL API.

ERR_NOT_FOUND:

  • Verify the project_id with LIST_PROJECTS. Use proj_<numeric_id> or a numeric id.

ERR_UNKNOWN_COMMAND or DESCRIBE_PROJECT:

  • DESCRIBE_PROJECT was removed. Use GET_PROJECT_LAYOUT(project_id) instead.

Support handoff:

  • Include the command called, full error envelope, current role, app name, source_object, and whether VALIDATE_SOURCE succeeds.

SETUP

Section titled “SETUP”

  1. Complete the EntryLayer app setup in the UI first. The SQL API expects the app organization and admin membership to exist.

  2. Grant the app admin application role to the Snowflake role used by Snowsight, Cortex Code, or your SQL client:

GRANT APPLICATION ROLE ENTRYLAYER.ENTRYLAYER_ADMIN TO ROLE MY_ADMIN_ROLE;

  1. Use a warehouse for your SQL worksheet/session when calling procedures from Snowsight or Cortex.

  2. Grant restricted caller rights for each source database/schema the app should describe:

GRANT CALLER USAGE ON DATABASE MY_DB TO APPLICATION ENTRYLAYER;

GRANT CALLER USAGE ON SCHEMA MY_DB.MY_SCHEMA TO APPLICATION ENTRYLAYER;

GRANT INHERITED CALLER REFERENCES, SELECT ON ALL TABLES IN SCHEMA MY_DB.MY_SCHEMA TO APPLICATION ENTRYLAYER;

For semantic views, grant caller rights sufficient for the app to DESCRIBE SEMANTIC VIEW MY_DB.MY_SCHEMA.MY_SEMANTIC_VIEW and read its referenced metadata.

  1. Validate source access before creating a project:

CALL ENTRYLAYER.API.VALIDATE_SOURCE(‘MY_DB.MY_SCHEMA.MY_TABLE’);

Notes:

  • Replace ENTRYLAYER with the installed application name in the consumer account.
  • SQL API procedures and APP_PUBLIC views are intentionally admin-only.
  • Source metadata discovery requires REFERENCES caller grants; source-backed grids and virtual-row materialization also require SELECT caller grants.
  • Project creation and source metadata validation do not sample source rows.
  • The consumer account must support Snowflake Native Apps with Snowpark Container Services.
Section titled “Related docs”