Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Risolvere i problemi relativi a Dataform

Questo documento mostra come risolvere i problemi relativi a Dataform.

Accesso a BigQuery negato

Il seguente errore si verifica quando attivi un'invocazione della pipeline prima di concedere a Dataform l'accesso a BigQuery:

Access Denied: Project PROJECT_ID: User does not have bigquery.jobs.create permission in project PROJECT_ID.

Per risolvere questo errore, concedi a Dataform l'accesso a BigQuery.

Il token di accesso per un repository remoto è stato rifiutato

Il seguente errore si verifica quando il token di autenticazione per un repository di terze parti connesso non ha accesso al repository:

The access token for remote repository REPOSITORY_NAME was rejected

Per risolvere questo errore, controlla le autorizzazioni richieste nel tuo provider Git e aggiorna il token di autenticazione di Secret Manager di conseguenza. Per saperne di più sull'autenticazione dei repository Git di terze parti in Dataform, consulta Connettiti a un repository Git di terze parti.

La connessione Secure Source Manager non dispone del proxy Developer Connect

Il seguente errore si verifica quando colleghi un repository Dataform a un repository Secure Source Manager (anteprima) utilizzando una connessione Developer Connect per cui non è abilitato il proxy:

This repository uses a Secure Source Manager connection that does not have the Developer Connect proxy enabled. Dataform cannot access it. Select a different repository, or link a new repository using a connection with the proxy enabled.

Per risolvere questo errore, seleziona un repository diverso, collega un nuovo repository utilizzando una connessione con il proxy abilitato o aggiorna la connessione Developer Connect esistente per abilitare il proxy. Per saperne di più, consulta Connetti un repository remoto utilizzando Developer Connect.

Limite di concorrenza delle query BigQuery superato

Il seguente errore si verifica quando il numero di query simultanee eseguite su BigQuery supera il limite di contemporaneità delle query di BigQuery:

Exceeded rate limits: too many concurrent queries for this project_and_region

Per risolvere questo errore, riduci il numero di query parallele a meno di 250 nei seguenti modi:

In Dataform, categorizza le azioni con i tag ed esegui solo i tag selezionati alla volta.
In Dataform, introduci le dipendenze tra le azioni.
In Dataform, dividi le esecuzioni delle azioni tra diversi progettiGoogle Cloud .

Per istruzioni su come risolvere questo errore in BigQuery, consulta Risolvi gli errori relativi a quote e limiti.

La quota BigQuery è stata superata

Il seguente errore si verifica quando il numero di richieste API che Dataform invia a BigQuery supera la quota di BigQuery:

Quota exceeded: Your user_method exceeded quota for concurrent api requests
per user per method.

Per risolvere questo errore, riduci il numero di query parallele a meno di 250 nei seguenti modi:

In Dataform, categorizza le azioni con i tag ed esegui solo i tag selezionati alla volta.
In Dataform, introduci le dipendenze tra le azioni.
In Dataform, dividi le esecuzioni delle azioni tra diversi progettiGoogle Cloud .

Per istruzioni su come risolvere questo errore in BigQuery, consulta Risolvi gli errori relativi a quote e limiti.

Errori di chiamata della pipeline BigQuery

I seguenti errori si verificano durante l'esecuzione di un workflow in BigQuery:

Errori di chiamata della pipeline che iniziano con Messaggi di errore di BigQuery.

Per risolvere questi errori, consulta Messaggi di errore di BigQuery.

La compilazione non va a buon fine

Durante la compilazione si verificano i seguenti errori a causa delle dimensioni o del numero di query compilate:

Compilation timed out. Reduce the complexity of your project to ensure it can compile within limits.
Compilation exceeded its allowed heap memory limits. Reduce the complexity of your project to ensure it can compile within limits.
Compilation exceeded its allowed ArrayBuffer or string memory limits. Reduce the complexity of your project to ensure it can compile within limits.
Compilation cancelled because it exceeded size limits.

Per risolvere questi errori, segui questi passaggi:

Aggiorna Dataform Core all'ultima versione.
Esamina il tuo flusso di lavoro per identificare e ridurre le inefficienze.
Riduci le dimensioni delle query SQL.

Riduci la quantità di operazioni JavaScript in memoria, ad esempio:

config { config {type: "table" }}
js {
    const tooBig = new Uint8Array(110_000_000);
}
SELECT ...

Suddividi il repository.

Per saperne di più sui limiti delle risorse di compilazione di Dataform, consulta Quote e limiti.

Proprietà `includeDependentAssertions` in conflitto

Il seguente errore si verifica durante la compilazione quando il parametro includeDependentAssertions è impostato per la stessa azione con valori diversi all'interno di un file:

Conflicting "includeDependentAssertions" properties are not allowed. Dependency
dependencyName has different values set for this property.

Per risolvere questo errore, modifica il file e rimuovi le ripetizioni in conflitto del parametro includeDependentAssertions.

Per saperne di più sull'utilizzo del parametro includeDependentAssertions per impostare le asserzioni come dipendenze, consulta Imposta le asserzioni di un'azione selezionata come dipendenze.

Il collegamento del account di servizio tra progetti è bloccato

Il seguente errore si verifica quando tenti di utilizzare un account di servizio personalizzato di un progetto diverso dal repository Dataform e l'operazione è bloccata da un vincolo della policy dell'organizzazione:

The caller does not have permission to act as service account: SERVICE_ACCOUNT_EMAIL

Per risolvere questo errore, segui questi passaggi:

Identifica il progetto Google Cloud in cui si trova il account di servizio personalizzato.
In quel progetto, disattiva il vincolo della policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage. Per saperne di più, consulta Abilita il collegamento dei service account tra progetti.
Assicurati che l'entità chiamante disponga del ruolo Service Account User (roles/iam.serviceAccountUser) nel account di servizio personalizzato.

Per saperne di più, consulta Gestisci il collegamento dei account di servizio tra progetti.

`@dataform/core` errori di dipendenza

Se la dipendenza dataform-core in package.json non è aggiornata, durante la compilazione si verificano i seguenti errori:

Failed to resolve @dataform/core

@dataform/core version should be X.X.X or newer

La dipendenza @dataform/core è obbligatoria in package.json. Quando inizializzi la prima area di lavoro nel repository, Dataform compila automaticamente package.json con la versione corrente di @dataform/core. Devi aggiornare @dataform/core all'ultima versione non appena viene rilasciata.

Per risolvere questi errori, aggiorna @dataform/core all'ultima versione.

Autorizzazione negata per le credenziali utente finale

Il seguente errore si verifica quando esegui il workload utilizzando le credenziali utente per un Account Google, ma Dataform non dispone delle autorizzazioni necessarie:

Dataform does not have the necessary permissions to run your workload using end user credentials. Error details: Account restricted: https://accounts.google.com/info/servicerestricted?...

Questo errore può verificarsi se la tua organizzazione utilizza regole di accesso sensibile al contesto che limitano l'accesso ai servizi Google Cloud in base all'identità e al contesto dell'utente.

Per risolvere questo errore, potrebbe essere necessario aggiornare la configurazione dell'accesso sensibile al contesto per consentire a Dataform di utilizzare le credenziali utente dell'Account Google. Per farlo, devi esentare l'ID client OAuth di Dataform nella configurazione del livello di accesso. Per informazioni dettagliate sull'esenzione delle applicazioni, consulta Configura i livelli di accesso per le applicazioni supportate.

Per ottenere l'ID client OAuth per Dataform, contatta l'assistenza clienti Google Cloud.

Impossibile risolvere `dataform.json`

Il seguente errore si verifica quando inizializzi un'area di lavoro Dataform, ma il processo di inizializzazione non riesce a installare tutti i pacchetti:

Uncaught Error: Failed to resolve dataform.json

Per risolvere questo errore, apri package.json nel tuo workspace e fai clic su Installa pacchetti.

Impossibile risolvere `workflow_settings.yaml`

Il seguente errore si verifica quando inizializzi un'area di lavoro Dataform, ma il processo di inizializzazione non riesce a installare tutti i pacchetti:

Uncaught Error: Failed to resolve workflow_settings.yaml

Per risolvere questo errore, apri workflow_settings.yaml nel tuo workspace e fai clic su Installa pacchetti.

I target del pacchetto `git+` non sono supportati

Il seguente errore si verifica quando definisci i pacchetti in package.json con target con prefisso git+:

'git+' prefixed package targets are not currently supported. However,
in most cases they can be used via a '.tar.gz' suffixed target instead.

Dataform non supporta i target dei pacchetti con prefisso git+.

Per risolvere questo errore, genera un URL tar.gz del pacchetto e aggiorna il target del pacchetto in package.json. Per saperne di più sull'installazione dei pacchetti in Dataform, consulta Installa un pacchetto.

Timeout dell'installazione del pacchetto

Il seguente errore si verifica quando le dimensioni dei pacchetti definiti in package.json superano le dimensioni massime delle dipendenze NPM:

API request error: Package installation timed out

Per risolvere questo errore, rimuovi i pacchetti ridondanti da package.json. Assicurati che il file package.json non contenga @dataform/cli e che la dimensione totale delle dipendenze NPM definite non superi i 200 MB.

Se le tue configurazioni di release fanno riferimento a commitish Git, assicurati che i file package.json nelle loro destinazioni siano validi.

Autorizzazione negata per agire come account di servizio

Il seguente errore si verifica quando l'entità che esegue l'azione non dispone dell'autorizzazione iam.serviceAccounts.actAs sul account di servizio effettivo:

Permission denied: Principal CALLER_EMAIL is missing 'iam.serviceAccounts.actAs' permission on service account SERVICE_ACCOUNT_EMAIL.

Questo errore può verificarsi durante le seguenti azioni:

Creazione o aggiornamento di un repository.
Creazione o aggiornamento di una configurazione del workflow.
Creazione di una chiamata del workflow.
Aggiornamento di una configurazione della release.

Per risolvere questo errore, concedi il ruolo Service Account User (roles/iam.serviceAccountUser) all'entità nel service account effettivo. Per saperne di più, consulta Concedi i ruoli IAM richiesti.

Impossibile raggiungere il registry dei pacchetti privati

Il seguente errore si verifica quando l'autenticazione di Dataform per un pacchetto privato scade:

Permission denied when fetching one or more npm packages. Please verify that
private registry authentication details are valid for each npm registry

Per risolvere questo errore, verifica che i dettagli di autenticazione del registry privato siano validi per ogni registry NPM. Per saperne di più, consulta Autentica un pacchetto privato.

Impossibile raggiungere il repository remoto

Uno dei seguenti errori si verifica quando Dataform non riesce a connettersi al repository Git remoto:

Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

Error during remote operation: SSH connection to remote repository 'REMOTE_REPOSITORY_URL' timed out.

Error during remote operation: `Read timed out`.

Error during remote operation: `Connection time out`.

Error during remote operation: The remote repository 'REMOTE_REPOSITORY_URL' closed connection during remote operation.

Il modo per risolvere questi errori di connessione dipende dal fatto che l'errore sia permanente o temporaneo.

Errori di connessione permanenti

Se l'errore si verifica costantemente a ogni tentativo di compilazione o durante la configurazione iniziale del repository, l'errore di connessione è permanente. La connessione non è configurata correttamente o le credenziali sono scadute. Per risolvere questo errore, segui questi passaggi:

Verifica che l'host del repository Git sia accessibile dalla rete internet pubblica.
Se il tuo repository Git remoto non è accessibile tramite internet pubblico, utilizza Developer Connect per connetterti in modo sicuro da Dataform.
Verifica che il token di autenticazione o le chiavi SSH siano validi, non scaduti e abbiano accesso al repository.
Segui tutti i passaggi descritti in Connettiti a un repository Git di terze parti.

Errori di connessione temporanei o intermittenti

Se l'errore si verifica sporadicamente durante le esecuzioni pianificate o quando più workflow vengono attivati contemporaneamente, l'errore di connessione è temporaneo. La connessione di rete esterna al repository remoto potrebbe essere temporaneamente inaffidabile.

Per ottimizzare l'affidabilità della produzione e prevenire errori di connessione temporanei, segui queste best practice:

Evita compilazioni frequenti di commitish in produzione: la chiamata diretta di CreateCompilationResult su un commitish Git, come main o un tag Git specifico, richiede a Dataform di eseguire un nuovo clone Git e installare i pacchetti sulla rete a ogni esecuzione. L'attivazione di compilazioni commitish frequenti in più pipeline aumenta la dipendenza dalla rete esterna e la latenza di esecuzione.
Utilizza le configurazioni della release: per l'esecuzione in produzione, utilizza le configurazioni della release. Una configurazione della release compila il repository in base a una pianificazione controllata e salva il risultato della compilazione immutabile. Le esecuzioni del workflow downstream utilizzano immediatamente questo risultato memorizzato nella cache senza eseguire query sul repository Git esterno.
Scagliona le esecuzioni pianificate: quando pianifichi più compilazioni o trigger di release, scagliona le pianificazioni cron per distribuire il carico di rete. Ad esempio, sfasa le pianificazioni di 5-10 minuti anziché eseguire tutti i job contemporaneamente.
Aggiungi nuovi tentativi nei workflow di orchestrazione: quando orchestri le compilazioni di Dataform da scheduler esterni come Managed Service for Apache Airflow, configura i nuovi tentativi automatici con backoff esponenziale sul tuo operatore per gestire in modo controllato l'affidabilità temporanea della rete. Ad esempio, in un DAG Airflow che utilizza DataformCreateCompilationResultOperator, configura i nuovi tentativi nel seguente modo:

from datetime import timedelta
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
)

create_compilation_result = DataformCreateCompilationResultOperator(
    task_id="create_compilation_result",
    project_id="PROJECT_ID",
    region="REGION",
    repository_id="REPOSITORY_ID",
    compilation_result={
        "git_commitish": "GIT_COMMITISH",
    },
    retries=5,
    retry_delay=timedelta(minutes=2),
    retry_exponential_backoff=True,
)

Repository non visibili in Dataform

Alcuni repository Dataform potrebbero essere visualizzati nelle ricerche di Cloud Asset Inventory o nei controlli delle autorizzazioni IAM, ma non in Dataform nella console Google Cloud .

Per scoprire come identificare l'origine di questi repository utilizzando le etichette, consulta Identificazione dei repository per gli asset BigQuery.

Il secret per un repository remoto non è accessibile

Il seguente errore si verifica quando l'agente di servizio Dataform non riesce ad accedere al secret di Secret Manager per un repository di terze parti connesso:

Dataform's service account is unable to reach the configured secret.
Make sure the secret exists and is shared with your Dataform service account:
SERVICE_ACCOUNT_ID.

Per risolvere questo errore, verifica che l'agente di servizio Dataform abbia accesso al secret.

Service account non visibile nel menu a discesa

Quando configuri un repository o una chiamata di workflow, il menu Service account potrebbe non elencare un account di servizio personalizzato esistente.

Dataform utilizza l'API Identity and Access Management per elencare i service account. Questa operazione richiede l'autorizzazione iam.serviceAccounts.list a livello di progetto.

Per risolvere questo problema, procedi in uno dei seguenti modi:

Fai clic su Inserisci manualmente e inserisci l'ID del account di servizio.
Chiedi all'amministratore del progetto di concederti il ruolo Service Account Viewer (roles/iam.serviceAccountViewer) o un altro ruolo che includa l'autorizzazione iam.serviceAccounts.list per il progetto.

Argomento sconosciuto: tag

Il seguente errore si verifica quando la tua versione dell'interfaccia a riga di comando di Dataform non riconosce l'argomento tags:

Unknown argument: tags