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

Neste documento, mostramos como resolver problemas com o Dataform.

O acesso ao BigQuery foi negado

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

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

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

O token de acesso de um repositório remoto foi 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 seu provedor do 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.

A conexão do Secure Source Manager não tem o proxy do Developer Connect

O erro a seguir ocorre quando você vincula um repositório do Dataform a um repositório do Secure Source Manager (pré-lançamento) usando uma conexão do Developer Connect que não tem o proxy ativado:

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.

Para resolver esse erro, selecione outro repositório, vincule um novo usando uma conexão com o proxy ativado ou atualize a conexão atual do Developer Connect para ativar o proxy. Para mais informações, consulte Conectar um repositório remoto usando o Developer Connect.

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 projetos doGoogle Cloud .

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

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 projetos doGoogle Cloud .

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

Erros de invocação do pipeline do BigQuery

Os seguintes erros ocorrem durante a execução de um fluxo de trabalho para o 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 seguintes erros ocorrem durante a compilação devido ao tamanho ou ao 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.
Compilation cancelled because it exceeded size limits.

Para resolver esses erros, siga estas etapas:

Atualize o Dataform Core para a versão mais recente.
Inspecione seu 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 conflitantes de `includeDependentAssertions`

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

O anexo da conta de serviço entre projetos está bloqueado

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 da 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 projeto do Google Cloud 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 de usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada.

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

Erros de dependência do `@dataform/core`

Os erros a seguir vão ocorrer 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 é obrigatória no package.json. Quando você inicializa 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 o @dataform/core para a versão mais recente assim que ela for lançada.

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

Permissão de credenciais do usuário final negada

O erro a seguir ocorre quando você executa a 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 serviços do Google Cloud com base na identidade e no contexto do usuário.

Para resolver esse erro, talvez seja necessário atualizar a configuração do acesso baseado no contexto para permitir que o Dataform use as 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 saber 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 seu 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 seu 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 aceita destinos de pacote com o prefixo 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.

A instalação do pacote expira

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

API request error: Package installation timed out

Para resolver esse erro, remova os 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 NPM definidas não excede 200 MB.

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

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

O erro a seguir ocorre quando o principal que executa 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 de usuário da conta de serviço (roles/iam.serviceAccountUser) ao principal na conta de serviço em vigor. Para mais informações, consulte Conceder os papéis necessários do IAM.

Não é possível acessar o registro de pacotes particulares

O seguinte erro ocorre quando a autenticação do Dataform para um pacote privado 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 foi 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 se a falha é 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 estiver acessível pela Internet pública, use o Developer Connect para se conectar com segurança pelo Dataform.
Verifique 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. Sua conexão de rede externa com o repositório remoto pode estar temporariamente instá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 específica do Git, exige que o Dataform execute um novo clone do Git e instale pacotes pela rede em cada execução. Acionar compilações frequentes de commitish em vários pipelines aumenta a dependência de rede externa e a latência de execução.
Use configurações de versão: para a execução de produção, use configurações de versão. Uma configuração de lançamento compila seu repositório em um cronograma controlado e salva o resultado imutável da compilação. As execuções de fluxo de trabalho downstream usam esse resultado armazenado em cache instantaneamente, sem consultar o repositório Git externo.
Escalonar execuções programadas: ao programar várias compilações ou gatilhos de lançamento, escalone as programações cron para distribuir a carga de rede. Por exemplo, defina um intervalo de 5 a 10 minutos entre as programações em vez de executar todos os jobs ao mesmo tempo.
Adicione novas tentativas nos 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 automáticas com espera exponencial no operador para lidar com a instabilidade temporária da rede. Por exemplo, em um DAG do Airflow que usa DataformCreateCompilationResultOperator, configure as 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 em pesquisas do Inventário de recursos do Cloud ou em auditorias de permissão do IAM, mas não aparecem no Dataform no console do Google Cloud .

Para saber como identificar a origem desses repositórios usando rótulos, consulte Como 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 de 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 requer a permissão iam.serviceAccounts.list no nível do projeto.

Para resolver o problema, siga um destes procedimentos:

Clique em Inserir manualmente e digite o ID da conta de serviço.
Peça ao administrador do projeto para conceder a você o papel de visualizador 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 argumento tags:

Unknown argument: tags