Solução de problemas da Amazon QLDB

Importante

Aviso de fim do suporte: os clientes existentes poderão usar a Amazon QLDB até o final do suporte em 31/07/2025. Para obter mais detalhes, consulte Migrar um Amazon QLDB Ledger para o Amazon Aurora Postgre. SQL

As seções a seguir fornecem uma lista agregada de erros comuns que você pode encontrar ao usar a Amazon QLDB e orientações sobre como solucioná-los.

Para obter orientações específicas sobre solução de problemas de IAM acesso, consulteSolução de problemas de QLDB identidade e acesso da Amazon.

Para obter as melhores práticas para ajustar suas instruções partiQL, consulte Otimizar a performance da consulta.

Executando transações usando o QLDB driver

Esta seção lista exceções comuns que o QLDB driver da Amazon pode retornar quando você o usa para executar transações partiQL em um livro contábil. Para obter mais informações sobre esse recurso, consulte Conceitos básicos do driver. Para obter as melhores práticas para configurar e usar o driver, consulte Recomendações de driver.

Cada exceção inclui a mensagem de erro específica, seguida por uma breve descrição e sugestões de possíveis soluções.

CapacityExceededException

Mensagem: Capacidade excedida

A Amazon QLDB rejeitou a solicitação porque ela excedeu a capacidade de processamento do livro contábil. QLDBimpõe um limite de escala interno por livro contábil para manter a integridade e o desempenho do serviço. Esse limite varia de acordo com o tamanho da workload de cada solicitação individual. Por exemplo, uma solicitação pode ter uma workload maior se realizar transações de dados ineficientes, como varreduras de tabelas resultantes de uma consulta qualificada não indexada.

Recomendamos que você espere antes de repetir a solicitação. Se seu aplicativo encontrar essa exceção de forma consistente, otimize suas instruções e diminua a taxa e o volume das solicitações que você envia para o ledger. Exemplos de otimização de instruções incluem a execução de menos instruções por transação e o ajuste dos índices da tabela. Para saber como otimizar instruções e evitar varreduras de tabelas, consulte Otimizar a performance da consulta.

Também recomendamos usar a versão mais recente do QLDB driver. O driver tem uma política de repetição padrão que usa recuo exponencial e Jitter para repetir automaticamente exceções como essa. O conceito por detrás do recuo exponencial é usar esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas.

InvalidSessionException

Mensagem: Transação transactionId expirou

Uma transação excedeu sua vida útil máxima. Uma transação pode ser executada por até 30 segundos antes de ser confirmada. Após esse limite de tempo limite, qualquer trabalho realizado na transação é rejeitado e a sessão é QLDB descartada. Esse limite protege o cliente de sessões vazadas ao iniciar transações e não confirmá-las ou cancelá-las.

Se essa for uma exceção comum em seu aplicativo, é provável que as transações estejam simplesmente demorando muito para serem executadas. Se o runtime da transação estiver demorando mais de 30 segundos, otimize seus extratos para acelerar as transações. Exemplos de otimização de instruções incluem a execução de menos instruções por transação e o ajuste dos índices da tabela. Para ter mais informações, consulte Otimizar a performance da consulta.

InvalidSessionException

Mensagem: Sessão sessionId expirou

QLDBdescartou a sessão porque ela excedeu sua vida útil total máxima. QLDBdescarta as sessões após 13 a 17 minutos, independentemente de uma transação ativa. As sessões podem ser perdidas ou prejudicadas por vários motivos, como falha de hardware, falha de rede ou reinicialização de aplicativos. Portanto, QLDB impõe uma vida útil máxima às sessões para garantir que o software cliente seja resiliente a falhas de sessão.

Se você encontrar essa exceção, recomendamos que você adquira uma nova sessão e repita a transação. Também recomendamos usar a versão mais recente do QLDB driver, que gerencia o pool de sessões e sua integridade em nome do aplicativo.

InvalidSessionException

Mensagem: Essa sessão não existe

O cliente tentou fazer transações QLDB usando uma sessão que não existe. Supondo que o cliente esteja usando uma sessão que existia anteriormente, a sessão pode não existir mais devido a um dos seguintes motivos:

• Se uma sessão estiver envolvida em uma falha interna do servidor (ou seja, um erro com o código de HTTP resposta 500), QLDB pode optar por descartar a sessão completamente, em vez de permitir que o cliente faça transações com uma sessão de estado incerto. Então, qualquer nova tentativa nessa sessão falhará com esse erro.

• As sessões expiradas acabam sendo esquecidas porQLDB. Então, qualquer tentativa de continuar usando a sessão resultará nesse erro, em vez do InvalidSessionException inicial.

Se você encontrar essa exceção, recomendamos que você adquira uma nova sessão e repita a transação. Também recomendamos usar a versão mais recente do QLDB driver, que gerencia o pool de sessões e sua integridade em nome do aplicativo.

RateExceededException

Mensagem: A taxa foi excedida

QLDBlimitou um cliente com base na identidade do chamador. QLDBimpõe a limitação por região e por conta usando um algoritmo de limitação de token bucket. QLDBfaz isso para ajudar no desempenho do serviço e para garantir o uso justo para todos os QLDB clientes. Por exemplo, tentar adquirir um grande número de sessões simultâneas usando a operação StartSessionRequest pode levar ao controle de utilização.

Para manter a integridade do aplicativo e reduzir ainda mais o controle de utilização, você pode tentar novamente essa exceção usando recuo exponencial e jitter. O conceito por detrás do recuo exponencial é usar esperas progressivamente mais longas entre as novas tentativas para respostas de erro consecutivas. Recomendamos usar a versão mais recente do QLDB driver. O driver tem uma política de repetição padrão que usa recuo exponencial e Jitter para repetir automaticamente exceções como essa.

A versão mais recente do QLDB driver também pode ajudar se seu aplicativo estiver constantemente sendo limitado QLDB para StartSessionRequest fazer chamadas. O driver mantém um pool de sessões que são reutilizadas em todas as transações, o que pode ajudar a reduzir o número de chamadas StartSessionRequest que seu aplicativo faz. Para solicitar um aumento nos limites de API limitação, entre em contato com o AWS Support Centro.

LimitExceededException

Mensagem: Excedeu o limite da sessão

Um ledger excedeu sua cota (também conhecida como limite) no número de sessões ativas. Essa cota é definida em Cotas e limites na Amazon QLDB. Eventualmente, a contagem de sessões ativas de um ledger é consistente, e ledgers consistentemente próximos à cota podem ver essa exceção periodicamente.

Para manter a integridade do seu aplicativo, recomendamos tentar novamente essa exceção. Para evitar essa exceção, certifique-se de não ter configurado mais de 1.500 sessões simultâneas para serem usadas em um único ledger em todos os clientes. Por exemplo, você pode usar o maxConcurrentTransactionsmétodo do QLDBdriver Amazon para Java para configurar o número máximo de sessões disponíveis em uma instância do driver.

QldbClientException

Mensagem: Um resultado transmitido só é válido quando a transação principal está aberta

A transação está fechada e não pode ser usada para recuperar os resultados. QLDB Uma transação é fechada quando é confirmada ou cancelada.

Essa exceção ocorre quando o cliente está trabalhando diretamente com o Transaction objeto e está tentando recuperar os resultados QLDB após confirmar ou cancelar uma transação. Para mitigar esse problema, o cliente deve ler os dados antes de fechar a transação.

Exportação de dados do diário

Esta seção lista exceções comuns que QLDB podem retornar quando você exporta dados do diário de um livro contábil para um bucket do Amazon S3. Para obter mais informações sobre esse recurso, consulte Exportação de dados de periódicos da Amazon QLDB.

Cada exceção inclui a mensagem de erro específica, seguida por uma breve descrição e sugestões de possíveis soluções.

AccessDeniedException

Mensagem: Usuário: userARN não está autorizado a executar: iam: PassRole no recurso: roleARN

Você não tem permissões para passar uma IAM função para o QLDB serviço. QLDBrequer uma função para todas as solicitações de exportação de periódicos, e você deve ter permissões para passar essa função paraQLDB. A função QLDB fornece permissões de gravação em seu bucket específico do Amazon S3.

Verifique se você define uma IAM política que conceda permissão para realizar a PassRole API operação no recurso de IAM função especificado para o QLDB serviço (qldb.amazonaws.com). Para ver um exemplo de política, consulte Exemplos de políticas baseadas em identidade para a Amazon QLDB.

IllegalArgumentException

Mensagem: QLDB encontrou um erro ao validar a configuração do S3: errorCode errorMessage

Uma possível causa desse erro é que o bucket do Amazon S3 fornecido não existe no Amazon S3. Ou QLDB não tem permissões suficientes para gravar objetos no bucket especificado do Amazon S3.

Verifique se o nome do bucket do S3 fornecido na solicitação de trabalho de exportação está correto. Para obter informações sobre a nomenclatura de buckets, consulte Restrições e limitações do bucket no Guia do usuário do Amazon Simple Storage Service.

Além disso, verifique se você define uma política para o bucket especificado que concede PutObject e PutObjectAcl autoriza o QLDB serviço (qldb.amazonaws.com). Para saber mais, consulte Permissões de exportação.

IllegalArgumentException

Mensagem: Resposta inesperada do Amazon S3 ao validar a configuração do S3. Resposta do S3: errorCode errorMessage

A tentativa de gravar dados de exportação do diário no bucket do S3 fornecido falhou com a resposta de erro fornecida pelo Amazon S3. Para obter mais informações sobre as causas possíveis, consulte Solução de problemas do Amazon S3 no Guia do usuário do Amazon Simple Storage Service.

IllegalArgumentException

Mensagem: O prefixo do bucket do Amazon S3 não deve exceder 128 caracteres

O prefixo fornecido na solicitação de exportação do diário contém mais de 128 caracteres.

IllegalArgumentException

Mensagem: A data de início não deve ser maior que a data de término

Ambos InclusiveStartTime ExclusiveEndTime devem estar no formato de data e hora ISO8601 e no Tempo Universal Coordenado ()UTC.

IllegalArgumentException

Mensagem: A data de término não pode ser no futuro

Ambos InclusiveStartTime ExclusiveEndTime devem estar no formato de ISO 8601 data e hora e emUTC.

IllegalArgumentException

Mensagem: A configuração de criptografia de objeto fornecida (S3EncryptionConfiguration) não é compatível com uma chave AWS Key Management Service (AWS KMS)

Você forneceu um KMSKeyArn com um ObjectEncryptionType de NO_ENCRYPTION ou SSE_S3. Você só pode fornecer um cliente gerenciado AWS KMS key para um tipo de criptografia de objeto de SSE_KMS. Para obter mais informações sobre o uso da criptografia no lado do servidor no Amazon S3, consulte Proteger dados usando criptografia no lado do servidor, no Guia do desenvolvedor do Amazon S3.

LimitExceededException

Mensagem: Excedeu o limite de 2 trabalhos de exportação de diário em execução simultânea

QLDBimpõe um limite padrão de dois trabalhos simultâneos de exportação de diário.

Streaming de dados do diário

Esta seção lista exceções comuns que QLDB podem retornar quando você transmite dados do diário de um livro contábil para o Amazon Kinesis Data Streams. Para obter mais informações sobre esse recurso, consulte Streaming de dados de diários da Amazon QLDB.

Cada exceção inclui a mensagem de erro específica, seguida por uma breve descrição e sugestões de possíveis soluções.

AccessDeniedException

Mensagem: Usuário: userARN não está autorizado a executar: iam: PassRole no recurso: roleARN

Você não tem permissões para passar uma IAM função para o QLDB serviço. QLDBrequer uma função para todas as solicitações de stream do diário, e você deve ter permissões para transmitir essa função paraQLDB. A função QLDB fornece permissões de gravação em seu recurso específico do Amazon Kinesis Data Streams.

Verifique se você define uma IAM política que conceda permissão para realizar a PassRole API operação no recurso de IAM função especificado para o QLDB serviço (qldb.amazonaws.com). Para ver um exemplo de política, consulte Exemplos de políticas baseadas em identidade para a Amazon QLDB.

IllegalArgumentException

Mensagem: QLDB encontrou um erro ao validar o Kinesis Data Streams: Resposta do Kinesis: errorCode errorMessage

Uma possível causa desse erro é que o recurso Kinesis Data Streams fornecido não existe. Ou QLDB não tem permissões suficientes para gravar registros de dados no stream de dados especificado do Kinesis.

Verifique se o fluxo de dados do Kinesis que você fornece na sua solicitação de fluxo está correto. Para obter mais informações, consulte Criar e atualizar fluxos de dados no Guia do desenvolvedor do Amazon Kinesis Data Streams.

Além disso, verifique se você define uma política para o stream de dados do Kinesis especificado que conceda ao QLDB service (qldb.amazonaws.com) permissões para as seguintes ações. Para ter mais informações, consulte Permissões de fluxo.

• kinesis:PutRecord

• kinesis:PutRecords

• kinesis:DescribeStream

• kinesis:ListShards

IllegalArgumentException

Mensagem: Resposta inesperada do Kinesis Data Streams ao validar a configuração do Kinesis. Resposta do Kinesis: errorCode errorMessage

A tentativa de gravar registros de dados no fluxo de dados do Kinesis fornecido falhou com a resposta de erro fornecida do Kinesis. Para obter mais informações sobre as causas possíveis, consulte Solução de problemas dos produtores do Amazon Kinesis Data Streams no Guia do usuário do Amazon Kinesis Data Streams.

IllegalArgumentException

Mensagem: A data de início não deve ser maior que a data de término.

Ambos InclusiveStartTime ExclusiveEndTime devem estar no formato de data e hora ISO8601 e no Tempo Universal Coordenado ()UTC.

IllegalArgumentException

Mensagem: A data de início não pode ser no futuro

Ambos InclusiveStartTime ExclusiveEndTime devem estar no formato de ISO 8601 data e hora e emUTC.

LimitExceededException

Mensagem: Excedeu o limite de 5 fluxos de registro em execução simultânea no Kinesis Data Streams

QLDBimpõe um limite padrão de cinco fluxos de diário simultâneos.

Verificação dos dados do diário

Esta seção lista as exceções comuns que QLDB podem retornar quando você verifica os dados do diário em um livro contábil. Para obter mais informações sobre esse recurso, consulte Verificação de dados na Amazon QLDB.

Cada exceção inclui a mensagem de erro específica, seguida pelas API operações que podem gerá-la, uma breve descrição e sugestões de possíveis soluções.

IllegalArgumentException

Mensagem: O valor de Ion fornecido não é válido e não pode ser analisado.

APIoperações: GetDigest, GetBlock, GetRevision

Certifique-se de fornecer um valor válido do Amazon Ion antes de tentar novamente sua solicitação.

IllegalArgumentException

Mensagem: O endereço de bloco fornecido não é válido.

APIoperações: GetDigest, GetBlock, GetRevision

Certifique-se de fornecer um valor válido de endereço de bloco antes de tentar novamente sua solicitação. Um endereço de bloco é uma estrutura Amazon Ion que tem dois campos: strandId e sequenceNo.

Por exemplo: {strandId:"BlFTjlSXze9BIh1KOszcE3",sequenceNo:14}

IllegalArgumentException

Mensagem: O número de sequência do endereço da dica de resumo fornecido está além do último registro confirmado da cadeia.

APIoperações: GetDigest, GetBlock, GetRevision

O endereço da dica de resumo que você fornecer deve ter um número de sequência menor ou igual ao número de sequência do último registro confirmado da vertente do diário. Antes de repetir sua solicitação, certifique-se de fornecer um endereço de sugestão com um número de sequência válido.

IllegalArgumentException

Mensagem: O ID de cadeia do endereço de bloco fornecido não é válido.

APIoperações: GetDigest, GetBlock, GetRevision

O endereço de bloco que você fornece deve ter um ID de cadeia que corresponda ao ID da cadeia do diário. Certifique-se de fornecer um valor válido de endereço de bloco antes de tentar novamente com um ID de cadeia.

IllegalArgumentException

Mensagem: O número de sequência do endereço de bloco fornecido está além do último registro confirmado da cadeia.

APIoperações: GetBlock, GetRevision

O endereço de bloco que você fornece deve ter um número de sequência menor ou igual ao número de sequência do último registro confirmado da cadeia. Antes de repetir sua solicitação, certifique-se de fornecer um endereço de bloco com um número de sequência válido.

IllegalArgumentException

Mensagem: O ID de cadeia do endereço de bloco fornecido deve corresponder ao ID de cadeia do endereço da dica de resumo fornecido.

APIoperações: GetBlock, GetRevision

Você só pode verificar uma revisão ou bloco de documento se ele existir na mesma linha do diário que o resumo fornecido.

IllegalArgumentException

Mensagem: O número de sequência do endereço de bloco fornecido não deve ser maior que o número de sequência do endereço de dica de resumo fornecido.

APIoperações: GetBlock, GetRevision

Você só pode verificar uma revisão ou bloco de documento se estiver coberto pelo mesmo resumo que você forneceu. Isso significa que foi entregue ao diário antes do endereço da dica de resumo.

IllegalArgumentException

Mensagem: O ID do documento fornecido não foi encontrado no bloco no endereço de bloco especificado.

APIoperação: GetRevision

O ID do documento que você fornece deve existir no endereço de bloco fornecido. Antes de repetir sua solicitação, verifique se esses dois parâmetros são consistentes.