O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 ao BigQuery para o Dataform.

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 esse repositório:

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. Para mais informações sobre como autenticar repositórios Git de terceiros no Dataform, consulte Conectar-se a um repositório Git de terceiros.

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.

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.

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.

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.

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 vinculação de conta de serviço entre projetos está bloqueada

O erro a seguir ocorre quando você tenta usar uma conta de serviço personalizada de um projeto diferente do repositório do Dataform, e a operação é bloqueada por uma restrição de política da organização:

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

Para resolver esse erro, faça o seguinte:

Identifique o Google Cloud projeto em que a conta de serviço personalizada está localizada.
Nesse projeto, desative a restrição de política da organização iam.disableCrossProjectServiceAccountUsage. Para mais informações, consulte Ativar a vinculação de contas de serviço entre projetos.
Verifique se o principal do autor da chamada tem o papel Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada.

Para mais informações, consulte Processar a vinculação conta de serviço entre projetos.

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.

Permissão de credenciais de usuário final negada

O erro a seguir ocorre quando você executa sua carga de trabalho usando credenciais de usuário para uma 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 aos 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.

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 compatíveis

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.

O pacote de instalação expira

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 versão fizerem referência a confirmações do Git, verifique se os package.json arquivos nos destinos são válidos.

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

O erro a seguir ocorre quando 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 versão.

Para resolver esse erro, conceda o papel 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.

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

Um dos erros a seguir ocorre quando o Dataform não consegue se conectar ao repositório 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.

A maneira de resolver esses erros de conexão depende de a falha ser permanente ou temporária.

Falhas de conexão permanentes

Se o erro ocorrer de forma consistente em todas as tentativas de compilação ou durante a configuração inicial do repositório, a falha de conexão será permanente. A conexão não está configurada corretamente ou as credenciais expiraram. Para resolver esse erro, siga estas etapas:

Confirme se o host do repositório Git pode ser acessado pela Internet pública.
Se o repositório Git remoto não puder ser acessado pela Internet pública, use Developer Connect para se conectar com segurança do Dataform.
Valide se o token de autenticação ou as chaves SSH são válidos, não expiraram e têm acesso ao repositório.
Siga todas as etapas em Conectar-se a um repositório Git de terceiros.

Falhas de conexão temporárias ou intermitentes

Se o erro ocorrer esporadicamente durante execuções programadas ou quando vários fluxos de trabalho forem acionados simultaneamente, a falha de conexão será temporária. A conexão de rede externa com o repositório remoto pode ser temporariamente não confiável.

Para otimizar a confiabilidade da produção e evitar erros de conexão temporários, siga estas práticas recomendadas:

Evite compilações frequentes de commitish na produção: chamar CreateCompilationResult diretamente em um commitish do Git, como main ou uma tag Git específica, exige que o Dataform execute um clone Git novo e instale pacotes na rede em cada execução. Acionar compilações frequentes de commitish em vários pipelines aumenta a dependência da rede externa e a latência de execução.
Use configurações de versão: para execução de produção, use configurações de versão. Uma configuração de versão compila o repositório em uma programação controlada e salva o resultado da compilação imutável. As execuções de fluxo de trabalho downstream usam esse resultado armazenado em cache instantaneamente sem consultar o repositório Git externo.
Escalone as execuções programadas: ao programar várias compilações ou acionadores de versão, escalone as programações do cron para distribuir a carga de rede. Por exemplo, desvie as programações em 5 a 10 minutos em vez de executar todos os jobs ao mesmo tempo.
Adicione novas tentativas em fluxos de trabalho de orquestração: ao orquestrar compilações do Dataform de programadores externos, como o Serviço Gerenciado para Apache Airflow, configure novas tentativas automatizadas com espera exponencial no operador para processar a instabilidade temporária da rede. Por exemplo, em um DAG do Airflow usando DataformCreateCompilationResultOperator, configure novas tentativas da seguinte maneira:

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,
)

Repositórios não visíveis no Dataform

Alguns repositórios do Dataform podem aparecer nas pesquisas do Inventário de recursos do Cloud ou nas auditorias de permissão do IAM, mas não aparecem no Dataform in Google Cloud console.

Para saber como identificar a origem desses repositórios usando rótulos, consulte Identificar repositórios para recursos do BigQuery.

O secret de um repositório remoto está inacessível

O erro a seguir ocorre quando o agente 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, verifique se o agente de serviço do Dataform tem acesso ao secret.

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

Argumento desconhecido: tags

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

Unknown argument: tags