Solução de problemas

Se a instalação não funciona, confira primeiro Node, plataforma e presença do runtime. Você não precisa instalar compiladores para usar o pacote pronto.

Runtime ausente

RUNTIME_AUSENTE costuma indicar que as dependências opcionais foram omitidas ou que o pacote da plataforma não foi instalado.

npm install cosmemilton-acbr-node --include=optional
npm ls cosmemilton-acbr-node

Na versão 0.1.0, você também pode instalar explicitamente o runtime correspondente. Use apenas a opção da sua plataforma:

# Linux x64
npm install cosmemilton-acbr-node-linux-x64@0.1.0

# Windows x64
npm install cosmemilton-acbr-node-win32-x64@0.1.0

Mantenha o SDK e o runtime na mesma versão. Se usa runtimeDirectory, ele precisa apontar para o diretório que contém manifest.json e todos os arquivos do motor.

Contrato divergente ou runtime alterado

CONTRATO_DIVERGENTE indica cliente e motor de gerações diferentes. Reinstale versões compatíveis ou gere e compile juntos os artefatos da sua revisão própria.

RUNTIME_ALTERADO indica um arquivo que não corresponde ao hash do manifesto. Não edite o manifesto para ignorar a verificação. Reinstale o pacote ou reconstrua seu runtime pelo fluxo completo.

Linux, Alpine e arquitetura

node -p "process.platform + ' ' + process.arch"

A release inicial exige linux x64 ou win32 x64. O Linux distribuído foi validado no Ubuntu 24.04/glibc; ele não é um binário portátil para Alpine/musl, macOS ou ARM.

Se o executável não inicia, confira permissões de execução, restrições do serviço e se a pasta de instalação está montada com noexec.

Windows e pasta WSL

npm.cmd pode apresentar problema quando o diretório atual é um caminho UNC, como \\wsl.localhost\.... Use uma pasta local do Windows ou o terminal Linux do WSL.

Uma aplicação Windows deve usar o runtime Windows; uma aplicação executada pelo Node Linux do WSL usa o runtime Linux. A plataforma é a do processo Node, não a do editor.

XML sem assinatura não valida

O primeiro guia gera XML sem A1. A estrutura completa NF-e exige Signature; uma validação de schema pode falhar até que a assinatura seja aplicada.

Siga Certificado A1 e assinatura. Isso continua sendo diferente de autorização fiscal.

Campo desconhecido ou decimal incorreto

Confira a grafia: Emit não é emit; Det é uma coleção de itens; o grupo de pagamento se chama pag.

Valores decimais são strings, como '10.00', não 10. Enums usam os nomes ACBr, como 'tnSaida'. Veja Modelos.

Certificado ou CSC

Informe uma única origem do A1 (pfx ou arquivo) e a senha em string. Confira se o arquivo é legível pelo usuário do serviço e se sua identidade é compatível com o emitente. Para assinar NFC-e, configure o CSC do ambiente correspondente.

Se uma conexão TLS falha, confira a data/hora do sistema e a cadeia de CAs confiáveis. A biblioteca verifica cadeia e hostname; não há configuração pública para desativar essas verificações.

Para TLS_SERVIDOR_INVALIDO, diferenças entre Windows e Linux ou uma CA ausente, siga TLS no Linux: diagnóstico e correção segura. O guia separa a confiança do motor nativo da configuração HTTPS do processo Node.js.

Timeout em operação fiscal

Confira resultadoDesconhecido no erro e preserve os dados da operação. Não transmita de novo automaticamente. Leia Erros e recuperação.

doctor pede Free Pascal ou SVN

doctor verifica ferramentas para obter fontes e reconstruir o motor. A ausência de um compilador não comprova falha no consumo do pacote pronto. Para conferir a instalação normal, execute o primeiro XML offline.

Como relatar um problema

Informe versão do pacote, Node, sistema/arquitetura, operação e código do erro. Use um exemplo sintético e remova PFX, senha, CSC e dados fiscais privados. Os problemas da biblioteca podem ser registrados no GitHub.