📦 Produto: TOTVS Microsiga Protheus
📚 Categoria: Framework | AppServer | Infraestrutura | Atualizações
🖥️ Aplicabilidade: Release 12.1.2510 e superiores, conforme documentação da TOTVS
📅 Data de publicação: 13/11/2026
👨💻 Autor: Fabrizio Augusto Ventavolo
🏅 Cargo: Consultor Especialista TOTVS — Mastersiga Consultoria
🏢 Departamento: Suporte Técnico Especializado — Mastersiga Consultoria
🔎 Palavras-chave: Protheus, LIB divergente, SpecialKey, RootPath, AppServer.ini, DBAccess, License Server, Homologação, Produção.
🎯 1. Objetivo
Este artigo apresenta como identificar, diagnosticar e corrigir a mensagem de utilização de LIBs divergentes no TOTVS Microsiga Protheus, especialmente em instalações nas quais os ambientes de Homologação e Produção utilizam versões diferentes da biblioteca, mas compartilham parâmetros ou diretórios de infraestrutura.
✅ O procedimento descrito foi aplicado com sucesso em um ambiente real, permitindo restabelecer o acesso à Homologação sem necessidade de interromper os serviços de Produção.
🚨 2. Descrição da ocorrência
Ao tentar acessar o ambiente de Homologação, o Protheus apresentou uma mensagem informando que havia outra conexão utilizando uma versão diferente da LIB.
No cenário analisado, foram identificadas as seguintes versões:
| 🖥️ Ambiente/conexão | 📦 Versão da LIB |
|---|---|
| Homologação | 20261016 |
| Conexão divergente | 20260817 |
A mensagem apresentava informações sobre o ambiente, as versões das bibliotecas e a conexão responsável pela divergência, incluindo endereço IP e identificação da thread.
Embora Homologação e Produção utilizassem bancos de dados e repositórios RPO distintos, existiam configurações compartilhadas que interferiam no mecanismo de controle de locks.
🔍 2.1. Por que ocorre o bloqueio?
Conforme a documentação oficial da TOTVS, a partir da LIB 20260119, na release 12.1.2510, foi implementada uma validação que impede a utilização simultânea de bibliotecas diferentes em um mesmo ambiente lógico.
O mecanismo utiliza um controle de bloqueio (lock) para identificar conexões concorrentes e evitar a execução de versões incompatíveis da biblioteca.
🛡️ Essa proteção tem como objetivo preservar a estabilidade, a segurança e a integridade operacional do ERP.
A TOTVS também esclarece que a utilização da chave SpecialKey interfere na identificação desses locks.
Dessa forma, configurações inadequadas podem fazer com que ambientes independentes sejam interpretados como pertencentes ao mesmo contexto de bloqueio.
🧩 3. Causa identificada
Durante a análise dos arquivos appserver.ini, constatou-se que os ambientes possuíam bancos de dados e RPOs diferentes, porém utilizavam o mesmo diretório RootPath e a mesma identificação SpecialKey.
📋 3.1. Configuração anterior
| ⚙️ Parâmetro | 🧪 Homologação | 🏭 Produção |
|---|---|---|
| Banco de dados | ERP_HML | ERP_PRD |
| RPO | Independente | Independente |
| RootPath | Protheus_Data | Protheus_Data |
| SpecialKey | Producao | Producao |
| StartPath | \system\homologacao | \system\producao |
Nomes de bancos e diretórios apresentados de forma ilustrativa.
Os parâmetros responsáveis pela sobreposição eram:
RootPath=D:\TOTVS\Protheus_Data\
SpecialKey=ProducaoAmbos os ambientes utilizavam essas mesmas definições.
Apesar da existência de diretórios de sistema específicos em StartPath, a configuração compartilhada da SpecialKey constituía um ponto de conflito para o controle de locks.
⚠️ Causa técnica: ausência de segregação adequada dos ambientes, especialmente na identificação utilizada pelo mecanismo de bloqueio das bibliotecas.
A correção dessa configuração eliminou a mensagem no caso analisado.
🛠️ 4. Solução aplicada
A solução consistiu na criação de um diretório RootPath exclusivo para Homologação e na definição de uma SpecialKey independente, preservando integralmente a configuração de Produção.
🔎 4.1. Etapa 1 — Análise da infraestrutura
Inicialmente, foram identificados e comparados os seguintes parâmetros:
📂
RootPath: diretório de dados utilizado pelo ambiente.📦
SourcePath: localização do repositório de objetos (RPO).🗂️
StartPath: diretório inicial de arquivos de sistema e dicionário.🔑
SpecialKey: identificação utilizada em mecanismos de controle de concorrência.🗄️
DBAccess: servidor, porta e alias do banco de dados.⚙️
App_Environment: ambiente associado à instância do AppServer.
Também foi verificada a existência de serviços independentes para Homologação e Produção.
📁 4.2. Etapa 2 — Criação do diretório exclusivo
Foi criado um novo diretório para Homologação, mantendo o diretório original de Produção.
📂 Estrutura anterior:
D:\TOTVS\
Protheus_Data\
system\
homologacao\
producao\✅ Estrutura após a segregação:
D:\TOTVS\
Protheus_Data\ [PRODUÇÃO]
system\
producao\
Protheus_Data_Homologacao\ [HOMOLOGAÇÃO]
system\
homologacao\A estrutura acima representa a organização lógica desejada. Diretórios e arquivos adicionais necessários ao Protheus devem ser preservados conforme a instalação.
💾 4.3. Etapa 3 — Cópia dos arquivos
A cópia inicial foi realizada mantendo Produção em execução.
Em servidores Windows, a operação pode ser realizada utilizando o Robocopy:
robocopy "D:\TOTVS\Protheus_Data" "D:\TOTVS\Protheus_Data_Homologacao" /E /XJ /R:1 /W:1 /COPY:DAT /DCOPY:DAT /LOG:"D:\TOTVS\copia_homologacao.log"Os caminhos são exemplos e devem ser adaptados à instalação.
🛡️ Cuidados importantes:
💾 Realizar backup antes da intervenção.
⏸️ Manter Homologação parada durante a preparação.
🔒 Não excluir, mover ou modificar arquivos da origem.
📋 Verificar o relatório do Robocopy e identificar arquivos não copiados.
🔐 Confirmar as permissões necessárias para o serviço de Homologação.
🔗 Revisar arquivos de configuração, integrações e customizações que utilizem caminhos absolutos.
✅ Garantir que o novo diretório contenha os arquivos necessários ao funcionamento do ambiente.
⚠️ Atenção: a cópia de arquivos enquanto Produção está em execução não assegura, por si só, uma cópia consistente de todos os arquivos que possam estar sendo modificados. Para cenários que exigem consistência transacional, deve-se utilizar um mecanismo apropriado, como snapshot VSS ou janela de manutenção.
Não é recomendado utilizar parâmetros como /MOVE ou /MIR sem avaliação específica, devido ao risco de movimentação ou exclusão de arquivos.
⚙️ 4.4. Etapa 4 — Alteração do appserver.ini de Homologação
Com o diretório exclusivo preparado, o arquivo appserver.ini de Homologação foi ajustado.
📝 Configuração de referência:
[Homologacao]
SourcePath=D:\TOTVS\Protheus\apo\homologacao\
RootPath=D:\TOTVS\Protheus_Data_Homologacao\
StartPath=\system\homologacao\
SpecialKey=Homologacao
RpoDb=top
RpoLanguage=Portuguese
RpoVersion=120
LocalFiles=CTREE
StartSysInDB=1
[GENERAL]
App_Environment=Homologacao
CheckSpecialKey=1
[DBAccess]
DataBase=MSSQL
Server=SERVIDOR_SQL
Alias=ERP_HML
Port=7890O exemplo apresenta apenas os parâmetros relevantes ao procedimento. As demais configurações existentes devem ser preservadas.
✅ As alterações fundamentais são:
📂 Diretório exclusivo:
RootPath=D:\TOTVS\Protheus_Data_Homologacao\🔑 Identificação exclusiva:
SpecialKey=HomologacaoO diretório StartPath deve continuar apontando para a estrutura de sistema correspondente à Homologação.
O SourcePath deve permanecer associado ao RPO correto e o alias do DBAccess deve continuar apontando para o banco de Homologação.
🏭 4.5. Etapa 5 — Preservação de Produção
Nenhuma alteração foi necessária no RootPath, na SpecialKey ou no repositório de Produção.
A configuração permaneceu equivalente a:
[Producao]
RootPath=D:\TOTVS\Protheus_Data\
SpecialKey=Producao✅ A alteração foi limitada à instância de Homologação.
🔄 4.6. Etapa 6 — Reinicialização do AppServer
Após concluir as alterações e verificações, foi reiniciado exclusivamente o serviço do AppServer de Homologação.
O procedimento consiste em:
🔌 Encerrar as conexões ativas de Homologação.
🔎 Confirmar que não existem jobs ou serviços vinculados ao ambiente em execução.
⏹️ Interromper o AppServer de Homologação.
⚙️ Conferir o arquivo
appserver.iniatualizado.▶️ Inicializar novamente o serviço.
📋 Monitorar os logs de inicialização.
✅ Realizar novo acesso pelo SmartClient ou WebApp.
Quando existir mais de uma instância utilizando o mesmo ambiente, todas deverão ser consideradas na análise e na reinicialização controlada.
✅ 5. Resultado obtido
Após a segregação do RootPath e da SpecialKey, o acesso à Homologação foi restabelecido com sucesso.
🎉 A mensagem de LIBs divergentes deixou de ocorrer no acesso validado.
📊 5.1. Configuração resultante
| 🧩 Componente | 🧪 Homologação | 🏭 Produção |
|---|---|---|
| Banco SQL | Exclusivo | Exclusivo |
| RPO | Exclusivo | Exclusivo |
| RootPath | Exclusivo | Exclusivo |
| SpecialKey | Homologacao | Producao |
| LIB | 20261016 | Versão própria |
| AppServer | Independente | Independente |
✅ Resultado confirmado: a correção eliminou o bloqueio de acesso observado, sem necessidade de interromper o ambiente de Produção.
O sucesso do acesso não substitui as validações funcionais de numeração automática e gravação de registros, que devem fazer parte do encerramento técnico da intervenção.
🔐 6. Cuidados com a numeração automática
A alteração da SpecialKey exige atenção adicional ao controle de numeração automática do Protheus.
Em ambientes que utilizam o License Server para esse controle, a identificação configurada influencia as sequências associadas ao ambiente.
Ao mudar de:
SpecialKey=ProducaoPara:
SpecialKey=Homologacaoé necessário verificar se as sequências correspondentes à nova identificação estão adequadas aos registros existentes no banco de Homologação.
📋 Recomendações:
⚙️ Acessar o Configurador (SIGACFG).
🔢 Verificar a rotina
APCFG110 — Controle de Numeração.🔎 Conferir as sequências utilizadas pelas rotinas operacionais.
📦 Avaliar especialmente o controle associado à chave
@@@SD2, quando aplicável.🔑 Confirmar a configuração
CheckSpecialKey=1na seção[GENERAL].✅ Realizar testes controlados de inclusão e gravação.
⚠️ Uma configuração incorreta pode provocar duplicidades, saltos de numeração ou inconsistências em movimentações de estoque e documentos fiscais.
Não altere manualmente as sequências sem conferir os maiores valores existentes no banco e as orientações oficiais aplicáveis à release.
🗄️ 7. Alternativa técnica — Controle de locks pelo DBAccess
A TOTVS também disponibiliza o controle de locks e numeração automática por meio do DBAccess.
Nesse modelo, os controles são associados ao banco de dados utilizado pelo ambiente, reduzindo a dependência da SpecialKey para essa finalidade.
A partir da release 12.1.2510, a ativação desse mecanismo pode ser realizada pela rotina:
FwImportLsNumberA migração permite importar os controles de numeração do License Server para o DBAccess.
⚠️ Restrições importantes:
🔒 É necessário acesso exclusivo ao ambiente.
👨💻 A execução deve ocorrer com credenciais administrativas.
🔑 A importação considera a
SpecialKeyconfigurada na origem.🚫 Após a ativação do controle pelo DBAccess, não é possível retornar ao gerenciamento anterior pelo License Server.
Por esse motivo, essa alternativa deve ser tratada como uma mudança de arquitetura, com planejamento, backup, análise de sequências e validação técnica.
✅ Não foi necessário executar essa migração para solucionar o caso apresentado neste artigo.
🏆 8. Boas práticas recomendadas pela Mastersiga
Para evitar novos incidentes de LIBs divergentes, recomenda-se:
📂 Segregação: manter Homologação e Produção com diretórios, RPOs, bancos de dados e identificações adequadamente independentes.
⚙️ Padronização: garantir que os AppServers, slaves e serviços pertencentes ao mesmo ambiente utilizem configurações compatíveis.
🔄 Atualizações controladas: evitar aplicar LIBs com usuários ou processos ativos no mesmo ambiente. Reiniciar todas as instâncias necessárias após a atualização.
🧪 Homologação prévia: aplicar e validar atualizações primeiro em Homologação, antes de promover os pacotes para Produção.
💾 Proteção dos dados: executar backup e registrar a configuração anterior e posterior às alterações.
🔍 Auditoria: monitorar logs do AppServer, controles de numeração e processos críticos após qualquer mudança de infraestrutura.
📝 Documentação: manter um inventário técnico atualizado dos ambientes, incluindo seus diretórios, LIBs, instâncias, serviços e configurações.
❓ 9. Perguntas frequentes
❔ É possível utilizar LIBs diferentes em Homologação e Produção?
✅ Sim. Os ambientes podem utilizar versões diferentes da LIB quando estão corretamente segregados e não compartilham indevidamente os mecanismos de controle de concorrência.
❔ Basta alterar a SpecialKey para resolver o problema?
Não necessariamente.
Quando dois ambientes compartilham o mesmo Protheus_Data, a TOTVS orienta a utilização da mesma SpecialKey. Portanto, a alteração isolada dessa chave, mantendo os demais recursos compartilhados, pode produzir novos problemas.
No caso apresentado, a correção envolveu a separação do RootPath juntamente com a alteração da SpecialKey.
❔ É necessário parar Produção para criar o novo RootPath?
Não obrigatoriamente.
A preparação inicial do novo diretório pode ocorrer com Produção em funcionamento, desde que não sejam realizadas alterações na origem.
Entretanto, arquivos abertos ou modificados durante a cópia podem exigir tratamento adicional para garantir consistência.
❔ A atualização da LIB pode ser realizada com usuários conectados?
Na regra descrita pela TOTVS para a LIB 20260119, release 12.1.2510, a atualização da LIB com acessos concorrentes não é suportada. A aplicação deve ocorrer de forma exclusiva, seguida da reinicialização das instâncias necessárias.
❔ É necessário utilizar o mesmo License Server?
Não há impedimento, por si só, em utilizar um License Server compartilhado. O cuidado está na configuração dos mecanismos de locks e numeração, conforme a arquitetura adotada.
📚 10. Referências oficiais TOTVS
📘 LIBs divergentes — Framework (Linha Protheus)
https://centraldeatendimento.totvs.com/hc/pt-br/articles/38584527544727-Framework-Framework-Linha-Protheus-Mensagem-de-uso-de-Libs-divergentes
🔑 Chave SpecialKey e limite de conexões
https://centraldeatendimento.totvs.com/hc/pt-br/articles/360031798133-Framework-Linha-Protheus-Chave-SpecialKey-e-limite-de-conex%C3%B5es
⚙️ CheckSpecialKey — Configuração no AppServer
https://centraldeatendimento.totvs.com/hc/pt-br/articles/34672116970519-Cross-Segmentos-Backoffice-Protheus-SIGAFAT-A-chave-CheckSpecialKey-em-seu-ambiente-est%C3%A1-desligada-voc%C3%AA-deve-liga-la-para-seu-uso-da-se%C3%A7%C3%A3o-GENERAL
🔢 NUMSEQ — Saltos ou registros duplicados
https://centraldeatendimento.totvs.com/hc/pt-br/articles/33294983047063-Cross-Segmento-Backoffice-Linha-Protheus-SIGAEST-Salto-de-numera%C3%A7%C3%A3o-ou-registros-duplicados-no-NUMSEQ
🎯 11. Conclusão
A utilização de LIBs diferentes entre Homologação e Produção não representa, isoladamente, um problema no TOTVS Protheus.
O incidente pode ocorrer quando os ambientes compartilham configurações de infraestrutura que interferem no mecanismo de identificação e controle de locks.
✅ No cenário apresentado, a criação de um RootPath exclusivo para Homologação e a configuração de uma SpecialKey própria resolveram a ocorrência, preservando a operação de Produção.
🛡️ A segregação adequada permite maior segurança, previsibilidade e independência no processo de atualização mensal do ERP.
👨💻 12. Sobre o autor
Fabrizio Augusto Ventavolo
Consultor Especialista TOTVS — Mastersiga Consultoria
Profissional especializado em sistemas de gestão empresarial TOTVS, com atuação em infraestrutura, administração de ambientes, atualização de sistemas, análise de incidentes, parametrizações e desenvolvimento de soluções para o ERP Microsiga Protheus.
🌐 Website: https://mastersiga.com.br
🏢 Mastersiga Consultoria — Departamento Técnico
“Conectamos tecnologia, processos e pessoas para acelerar resultados com excelência em sistemas TOTVS.”
© 2026 Mastersiga Consultoria — Todos os direitos reservados.
Corrigir a assinatura profissional oficialSeparar diagnóstico de procedimento recomendado