Resolver problemas do Dataform

Este documento mostra como resolver problemas com o Dataform.

O acesso ao BigQuery é negado

O erro a seguir ocorre quando você aciona uma invocação de pipeline antes de conceder acesso ao BigQuery para o Dataform:

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

Para resolver esse erro, conceda acesso do Dataform ao BigQuery.

O token de acesso de um repositório remoto é rejeitado

O erro a seguir ocorre quando o token de autenticação de um repositório de terceiros conectado não tem acesso a ele:

The access token for remote repository REPOSITORY_NAME was rejected

Para resolver esse erro, verifique as permissões necessárias no provedor Git e atualize o token de autenticação do Secret Manager de acordo com elas. Para mais informações sobre como autenticar repositórios Git de terceiros no Dataform, consulte Conectar-se a um repositório Git de terceiros.

A cota do BigQuery foi excedida

O erro a seguir ocorre quando o número de solicitações de API que o Dataform envia ao BigQuery excede a cota do BigQuery:

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

Para resolver esse erro, reduza o número de consultas paralelas para menos de 250 das seguintes maneiras:

No Dataform, categorize ações com tags, e execute apenas as tags selecionadas por vez.
No Dataform, introduza dependências entre ações.
No Dataform, divida as execuções de ações entre diferentes Google Cloud projetos.

Para instruções sobre como resolver esse erro no BigQuery, consulte Resolver problemas de cota e limite erros.

O limite de simultaneidade de consultas do BigQuery foi excedido

O erro a seguir ocorre quando o número de consultas simultâneas executadas no BigQuery excede o limite de simultaneidade de consultas do BigQuery:

Exceeded rate limits: too many concurrent queries for this project_and_region

Para resolver esse erro, reduza o número de consultas paralelas para menos de 250 das seguintes maneiras:

No Dataform, categorize ações com tags, e execute apenas as tags selecionadas por vez.
No Dataform, introduza dependências entre ações.
No Dataform, divida as execuções de ações entre diferentes Google Cloud projetos.

Para instruções sobre como resolver esse erro no BigQuery, consulte Resolver problemas de cota e limite erros.

Erros de invocação de pipeline do BigQuery

Os erros a seguir ocorrem durante a execução de um fluxo de trabalho no BigQuery:

Erros de invocação de pipeline que começam com mensagens de erro do BigQuery.

Para resolver esses erros, consulte Mensagens de erro do BigQuery.

Propriedades `includeDependentAssertions` conflitantes

O erro a seguir ocorre durante a compilação quando o parâmetro includeDependentAssertions é definido para a mesma ação com valores diferentes em um arquivo:

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

Para resolver esse erro, edite o arquivo e remova repetições conflitantes do parâmetro includeDependentAssertions.

Para mais informações sobre como usar o parâmetro includeDependentAssertions para definir declarações como dependências, consulte Definir as declarações de uma ação selecionada como dependências.

A compilação está falhando

Os erros a seguir ocorrem durante a compilação devido ao tamanho ou número de consultas compiladas:

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.

Para resolver esses erros, siga estas etapas:

Atualize o Dataform Core para a versão mais recente.
Inspecione o fluxo de trabalho para identificar e reduzir ineficiências.
Reduza o tamanho das consultas SQL.

Reduza a quantidade de operações JavaScript na memória, por exemplo:

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

Divida o repositório.

Para mais informações sobre os limites de recursos de compilação do Dataform, consulte Cotas e limites.

Erros de dependência `@dataform/core`

Os erros a seguir ocorrem durante a compilação se a dependência dataform-core em package.json estiver desatualizada:

Failed to resolve @dataform/core

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

A dependência @dataform/core é necessária no package.json. Ao inicializar o primeiro espaço de trabalho no repositório, o Dataform preenche automaticamente package.json com a versão atual de @dataform/core. É necessário atualizar @dataform/core para a versão mais recente assim que ela for lançada.

Para resolver esses erros, atualize @dataform/core para a versão mais recente.

Falha ao resolver `dataform.json`

O erro a seguir ocorre quando você inicializa um espaço de trabalho do Dataform, mas o processo de inicialização não instala todos os pacotes:

Uncaught Error: Failed to resolve dataform.json

Para resolver esse erro, no espaço de trabalho, abra package.json e clique em Instalar pacotes.

Falha ao resolver `workflow_settings.yaml`

O erro a seguir ocorre quando você inicializa um espaço de trabalho do Dataform, mas o processo de inicialização não instala todos os pacotes:

Uncaught Error: Failed to resolve workflow_settings.yaml

Para resolver esse erro, no espaço de trabalho, abra workflow_settings.yaml e clique em Instalar pacotes.

Os destinos de pacote `git+` não são aceitos

O erro a seguir ocorre quando você define pacotes em package.json com destinos prefixados com git+:

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

O Dataform não oferece suporte a destinos de pacote prefixados com git+.

Para resolver esse erro, gere um URL tar.gz do pacote e atualize o destino do pacote em package.json. Para mais informações sobre como instalar pacotes no Dataform, consulte Instalar um pacote.

Permissão de credenciais de usuário final negada

O erro a seguir ocorre quando você executa a carga de trabalho usando credenciais de usuário da Conta do Google, mas o Dataform não tem as permissões necessárias:

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

Esse erro pode ocorrer se a organização usar regras de acesso baseado no contexto que restringem o acesso a Google Cloud serviços com base na identidade e no contexto do usuário.

Para resolver esse erro, talvez seja necessário atualizar a configuração de acesso baseado no contexto para permitir que o Dataform use credenciais de usuário da Conta do Google. Para fazer isso, é necessário isentar o ID do cliente OAuth do Dataform na configuração do nível de acesso. Para detalhes sobre como isentar aplicativos, consulte Configurar níveis de acesso para aplicativos compatíveis.

Para receber o ID do cliente OAuth do Dataform, entre em contato com o Cloud Customer Care.

O tempo limite da instalação do pacote expirou

O erro a seguir ocorre quando o tamanho dos pacotes definidos em package.json excede o tamanho máximo das dependências do NPM:

API request error: Package installation timed out

Para resolver esse erro, remova pacotes redundantes de package.json. Verifique se o arquivo package.json não contém @dataform/cli e se o tamanho total das dependências do NPM definidas não excede 200 MB.

Se as configurações de lançamento fizerem referência a commits do Git, verifique se os arquivos package.json nos destinos são válidos.

Permissão negada para agir como uma conta de serviço

O erro a seguir ocorre quando o modo de atuação estrita está ativado e o principal que realiza a ação não tem a permissão iam.serviceAccounts.actAs na conta de serviço efetiva:

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

Esse erro pode ocorrer durante as seguintes ações:

Criar ou atualizar um repositório.
Criar ou atualizar uma configuração de fluxo de trabalho.
Criar uma invocação de fluxo de trabalho.
Atualizar uma configuração de lançamento.

Para resolver esse erro, conceda o papel de usuário da conta de serviço (roles/iam.serviceAccountUser) ao principal na conta de serviço efetiva. Para mais informações, consulte Conceder os papéis necessários do IAM.

A conta de serviço não está visível no menu suspenso

Ao configurar um repositório ou uma invocação de fluxo de trabalho, o menu Conta de serviço pode não listar uma conta de serviço personalizada existente.

O Dataform usa a API Identity and Access Management para listar contas de serviço. Isso exige a permissão iam.serviceAccounts.list no nível do projeto.

Para resolver esse problema, faça uma das seguintes ações:

Clique em Inserir manualmente e digite o ID da conta de serviço.
Peça ao administrador do projeto para conceder o papel de Leitor de contas de serviço (roles/iam.serviceAccountViewer) ou outro papel que inclua a permissão iam.serviceAccounts.list no projeto.

Não é possível acessar o registro de pacote particular

O erro a seguir ocorre quando a autenticação do Dataform para um pacote particular expira:

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

Para resolver esse erro, verifique se os detalhes de autenticação do registro particular são válidos para cada registro do NPM. Para mais informações, consulte Autenticar um pacote particular.

Não é possível acessar o repositório remoto

O erro a seguir ocorre devido à instabilidade do Git ou quando a conexão do repositório de terceiros não foi configurada corretamente:

Remote repository REPOSITORY_NAME could not be reached.

Para resolver esse erro, verifique se todas as etapas listadas em Conectar-se a um repositório Git de terceiros foram seguidas. Em particular, confirme se o host do repositório Git está acessível na Internet pública. Além disso, valide se o token de autenticação ou a chave privada está correto e tem as permissões necessárias para acessar o repositório.

Não é possível acessar o repositório remoto: `generic::invalid_argument`

O erro a seguir ocorre na página Detalhes das configurações de lançamento quando um lançamento agendado encontra ocasionalmente uma conexão lenta, instável ou interrompida do GitHub, GitLab ou Bitbucket:

generic::invalid_argument: Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

Não é necessário fazer nada. A menos que os problemas do GitHub, GitLab ou Bitbucket Cloud persistam, os lançamentos programados subsequentes poderão ser bem-sucedidos.

Não é possível acessar o secret de um repositório remoto

O erro a seguir ocorre quando o agente de serviço ou a conta de serviço do Dataform não consegue acessar o secret do Secret Manager para um repositório de terceiros conectado:

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.

Para resolver esse erro, faça o seguinte:

Verifique se o agente de serviço ou a conta de serviço do Dataform tem acesso ao secret.
Exclua o secret do perímetro de serviço do VPC-SC. O Dataform não oferece suporte ao VPC-SC no momento.

Argumento desconhecido: tags

O erro a seguir ocorre quando a versão da CLI do Dataform não reconhece o argumento tags:

Unknown argument: tags