Por que a regra de rewrite não casa: use rewrite:trace3
Como ligar o rastreamento no escopo mais estreito, ler o bloco de uma requisição só e distinguir loop por reentrada, padrão com barra inicial e RewriteBase ausente. Inclui o procedimento de desligar com verificação.

Resposta curta: no Apache 2.4 o RewriteLog não existe mais; o rastreamento é `LogLevel warn rewrite:trace3`, com 8 níveis (trace1 a trace8), ligado em `<Directory>` e nunca em .htaccess. A linha `applying pattern 'P' to uri 'U'` mostra o que o motor realmente comparou.
Neste artigo
- O que substituiu o RewriteLog no Apache 2.4
- Ligue o trace só no diretório que você está depurando
- Como isolar as linhas de uma única requisição no error log
- O que cada linha do trace prova
- Três diagnósticos que o log fecha sozinho
- Como ligar o log de rewrite sob LiteSpeed em cPanel
- Desligar e provar que desligou
- Quando o log não mostra nenhuma linha de rewrite
O que substituiu o RewriteLog no Apache 2.4
As diretivas RewriteLog e RewriteLogLevel foram removidas no Apache 2.4. Se elas ainda aparecem em algum tutorial que você achou, o tutorial é de 2.2. Colocá-las numa configuração 2.4 gera erro de sintaxe no apachectl -t, e dentro de um .htaccess gera 500.
O que existe hoje é o LogLevel por módulo, com os níveis de rastreamento trace1 a trace8:
LogLevel warn rewrite:trace3
Isso significa: mantenha o servidor em warn para todo mundo e suba só o mod_rewrite para trace3. A saída vai para o ErrorLog do virtual host, misturada com o resto, e cada linha carrega o prefixo [rewrite:traceN], onde N é o nível em que aquela linha específica foi emitida, não o nível que você ligou: com trace3 ativo convivem no mesmo bloco linhas [rewrite:trace1], [rewrite:trace2] e [rewrite:trace3]. Por isso o filtro que funciona é grep -F '[rewrite:', sem o número.
Dois detalhes que derrubam a tentativa na primeira vez:
LogLeveltem contexto de configuração de servidor, virtual host e diretório. Não é permitido em.htaccess. Se o seu acesso ao servidor termina no.htaccess, não existe truque: ou alguém com acesso à configuração liga para você, ou você reproduz o caso fora da produção.- O
LogLeveldentro de<Directory>só vale depois que a requisição foi mapeada para aquele diretório. Para o rewrite em contexto per-dir (que é o caso do.htaccess) isso é suficiente, porque o per-dir acontece justamente depois do mapeamento.
Sob LiteSpeed a história é outra, e ela tem seção própria mais abaixo.
Ligue o trace só no diretório que você está depurando
Rastreamento de rewrite é caro. Uma requisição que hoje escreve zero linha passa a escrever dezenas, no mesmo arquivo em que você vai precisar enxergar alguma coisa. Então não suba o LogLevel do servidor inteiro. Suba do diretório que você está depurando, de preferência de um subdiretório que só o seu teste acessa.
# exemplo: dentro do <VirtualHost> do site
<Directory "/home/exemplo/public_html/produtos">
AllowOverride All
LogLevel warn rewrite:trace3
</Directory>
Antes de recarregar, valide e guarde o estado anterior:
# qual LogLevel está valendo hoje, e onde
grep -rn --include='*.conf' -E '^[[:space:]]*LogLevel' /etc/apache2/ /etc/httpd/ 2>/dev/null
apachectl -t && apachectl graceful
Qual nível usar, de trace1 a trace8
A escala vai de trace1 a trace8 e é cumulativa: trace3 inclui o que trace1 e trace2 imprimem. O nível exato em que cada linha é emitida pode variar entre versões do mod_rewrite; use a tabela como ponto de partida e, se a linha que você procura não aparecer, suba um nível.
| Nível | O que você costuma ganhar | Quando usar |
|---|---|---|
trace1 |
Início do motor, redirecionamento interno, pass through |
Só para saber se o .htaccess está sendo lido |
trace2 |
A substituição efetiva (rewrite 'a' -> 'b'), recolocação do prefixo per-dir |
Confirmar o resultado de uma regra que você sabe que casa |
trace3 |
strip per-dir prefix, applying pattern ... to uri ..., split uri |
Padrão para depurar regra que não casa |
trace4 |
Avaliação de cada RewriteCond (entrada, padrão, casou ou não) |
Quando o problema está na condição, não no padrão |
trace5 a trace8 |
Detalhes internos: mapas, cache, lookups, estruturas | Último recurso, e por poucos segundos |
Na prática, trace3 responde "por que esse padrão não casou" e trace4 responde "por que essa regra foi pulada mesmo com o padrão certo". Comece por trace3.
Como reproduzir em contêiner quando não há acesso ao VirtualHost
Reproduza em contêiner, com o mesmo .htaccess, e depure à vontade:
# 1) extrai a conf padrão da imagem oficial para editar
docker run --rm httpd:2.4 cat /usr/local/apache2/conf/httpd.conf > httpd.conf
# 2) em httpd.conf: descomente LoadModule rewrite_module,
# troque AllowOverride None por AllowOverride All no
# <Directory "/usr/local/apache2/htdocs"> e acrescente,
# dentro desse mesmo bloco: LogLevel warn rewrite:trace3
# 3) sobe com o seu site montado
docker run --rm -p 8080:80 \
-v "$PWD/httpd.conf":/usr/local/apache2/conf/httpd.conf:ro \
-v "$PWD/site":/usr/local/apache2/htdocs:ro \
httpd:2.4
Na imagem oficial o ErrorLog sai no stderr do contêiner, então docker logs -f já mostra o trace. Duas diferenças em relação à produção que você precisa ter em mente ao concluir qualquer coisa: o caminho absoluto do diretório muda (e caminho absoluto aparece nas linhas de per-dir), e a hospedagem pode estar rodando LiteSpeed, não Apache.
Como isolar as linhas de uma única requisição no error log
Com o trace ligado, o error log vira uma torrente. O objetivo é extrair o bloco de uma requisição só, inteiro, na ordem.
O identificador que amarra as linhas é o rid, que aparece no prefixo de cada linha junto com um marcador de passe: [rid#55a1c0/initial] na primeira passada e [rid#.../initial/redir#1], redir#2 e assim por diante a cada redirecionamento interno. Sub-requisições aparecem como /subreq. O detalhe que atrapalha: a cada redirecionamento interno o rid muda, então filtrar só por rid perde os saltos seguintes. Filtre por IP de origem e reconstrua a cadeia pelo contador redir#N.
# dispara de um IP conhecido, com marcador na query string
curl -s -o /dev/null "https://exemplo.com.br/produtos/123?trace=abc123"
# extrai só o que é rewrite, vindo daquele IP
grep -F '203.0.113.10' /var/log/apache2/error.log | grep -F '[rewrite:'
# só os saltos, para ver de cara se virou loop
grep -F '203.0.113.10' /var/log/apache2/error.log | grep -F 'redir#'
Se o site tem tráfego e o seu IP não é único, o jeito limpo é ligar o trace apenas num <Directory> que só o teste acessa, ou num vhost de staging com o mesmo .htaccess.
O que cada linha do trace prova
Abaixo, um exemplo ilustrativo (não é saída capturada de um servidor real, e o prefixo de data, pid e cliente foi abreviado a partir da segunda linha para caber na tela):
[Wed Sep 17 14:02:11.884210 2025] [rewrite:trace3] [pid 2841:tid 139] mod_rewrite.c: [client 203.0.113.10:51734] [perdir /home/exemplo/public_html/] strip per-dir prefix: /home/exemplo/public_html/produtos/123 -> produtos/123
... [rewrite:trace3] ... [perdir /home/exemplo/public_html/] applying pattern '^produtos/([0-9]+)$' to uri 'produtos/123'
... [rewrite:trace2] ... [perdir /home/exemplo/public_html/] rewrite 'produtos/123' -> 'index.php?id=123'
... [rewrite:trace3] ... split uri=index.php?id=123 -> uri=index.php, args=id=123
... [rewrite:trace2] ... [perdir /home/exemplo/public_html/] add per-dir prefix: index.php -> /home/exemplo/public_html/index.php
... [rewrite:trace1] ... [perdir /home/exemplo/public_html/] internal redirect with /index.php [INTERNAL REDIRECT]
Leia na ordem, e cada linha responde uma pergunta:
| Linha | O que ela prova |
|---|---|
strip per-dir prefix: /caminho/abs/x -> x |
O .htaccess foi lido e a URI que as regras vão ver não tem barra inicial |
applying pattern 'P' to uri 'U' |
O par exato que o motor comparou. Se não vier uma linha rewrite depois, P não casou com U |
RewriteCond: input='I' pattern='P' => matched (trace4) |
A condição foi avaliada, com o valor expandido de verdade |
rewrite 'A' -> 'B' |
A substituição ocorreu e B é o novo valor |
add per-dir prefix: B -> /caminho/abs/B |
A substituição relativa foi remontada em caminho de sistema de arquivos |
strip document_root prefix: /caminho/abs/B -> /B |
O caminho foi remapeado de volta para URL. Se essa linha falta, o mapeamento não é um prefixo simples |
internal redirect with /B [INTERNAL REDIRECT] |
Nova rodada do motor: o .htaccess será processado de novo |
pass through /B |
Nenhuma regra alterou nada nesta rodada, a requisição seguiu |
[rid#.../initial/redir#N] |
Contador de passes. N crescendo é o sintoma de loop |
A linha mais útil de todas é applying pattern. Ela mata o debate sobre "a regra está certa": mostra literalmente a string que o motor recebeu e o padrão que ele usou. É onde a maior parte dos casos de "não funciona" se resolve, quando você vê que a URI comparada não é a que você imaginava.
Três diagnósticos que o log fecha sozinho
Loop por reentrada no per-dir, e por que [L] não resolve
No contexto per-dir, uma substituição não encerra o processamento: ela dispara um redirecionamento interno, o servidor refaz a resolução de diretório e o mesmo .htaccess é processado outra vez. Se a nova URI ainda casa com a mesma regra, o ciclo se repete até o limite de recursão interna, que por padrão é 10 (LimitInternalRecursion).
No log (exemplo ilustrativo):
... [rid#5a10/initial] applying pattern '^(.*)$' to uri 'produtos/123'
... [rid#5a10/initial] rewrite 'produtos/123' -> 'index.php?rota=produtos/123'
... [rid#5b20/initial/redir#1] applying pattern '^(.*)$' to uri 'index.php'
... [rid#5b20/initial/redir#1] rewrite 'index.php' -> 'index.php?rota=index.php'
... [rid#5c30/initial/redir#2] applying pattern '^(.*)$' to uri 'index.php'
[core:error] [client 203.0.113.10] Request exceeded the limit of 10 internal redirects due to probable configuration error.
O padrão é inequívoco: o mesmo applying pattern repetido com redir# crescente e o erro de recursão do core no fim. O [L] não resolve, porque ele só encerra a rodada atual, e é exatamente uma nova rodada que começou.
Saídas, em ordem de preferência:
- Trocar
[L]por[END](disponível a partir do 2.3.9, portanto em todo 2.4), que encerra o processamento de rewrite para a requisição inteira e não reentra. - Excluir o alvo por condição, o clássico
RewriteCond %{REQUEST_FILENAME} !-fe!-d, ou uma condição explícita sobre a URI de destino. - Testar
%{ENV:REDIRECT_STATUS}vazio para só agir no primeiro passe.
Se o servidor for LiteSpeed, confirme o suporte ao END na versão em uso antes de depender dele.
Padrão com barra inicial que nunca casa em .htaccess
Este caso aparece inteiro em duas linhas:
... strip per-dir prefix: /home/exemplo/public_html/produtos/123 -> produtos/123
... applying pattern '^/produtos/([0-9]+)$' to uri 'produtos/123'
... pass through /home/exemplo/public_html/produtos/123
O padrão começa com /, a URI comparada não começa com /, nada casa, e a requisição passa direto. É a mesma regra que funcionaria sem alteração dentro de <VirtualHost>, porque lá a URI chega com a barra. Em .htaccess o prefixo do diretório é removido antes da comparação.
Correção: tire a barra inicial (^produtos/([0-9]+)$) ou torne-a opcional (^/?produtos/), que é o que salva a regra se o mesmo arquivo for incluído nos dois contextos.
RewriteBase ausente e o caminho do servidor vazando no Location
Substituição relativa em per-dir é remontada sobre o caminho de sistema de arquivos do diretório e depois precisa ser reconvertida em URL. Quando o diretório não é um prefixo simples da raiz de documentos (alias, link simbólico, subdomínio apontando para fora do docroot), essa reconversão falha e o caminho do servidor vaza.
... [perdir /home/exemplo/aplicacoes/loja/] rewrite 'carrinho' -> 'index.php?p=carrinho'
... [perdir /home/exemplo/aplicacoes/loja/] add per-dir prefix: index.php -> /home/exemplo/aplicacoes/loja/index.php
... escaping /home/exemplo/aplicacoes/loja/index.php for redirect
... redirect to http://exemplo.com.br/home/exemplo/aplicacoes/loja/index.php [REDIRECT/302]
O sinal é a ausência da linha strip document_root prefix e a presença do caminho do sistema de arquivos dentro do Location. O RewriteBase existe para informar manualmente qual prefixo de URL corresponde àquele diretório:
RewriteBase /loja/
Com ele, index.php vira /loja/index.php em vez de passear pelo sistema de arquivos. A alternativa é escrever substituições absolutas em URL, começando com /, que dispensam o RewriteBase.
Como ligar o log de rewrite sob LiteSpeed em cPanel
LiteSpeed lê o mesmo .htaccess e implementa as diretivas do mod_rewrite, mas não é o Apache: o LogLevel ... rewrite:traceN do Apache não é o que controla o log de reescrita do LSWS, e a saída não tem obrigação de sair no mesmo formato linha a linha.
A documentação oficial da LiteSpeed sobre rewrite logs em cPanel, consultada em 18/09/2026, descreve o seguinte:
- Onde se liga: no WebAdmin Console do LSWS (por padrão em
https://IP:7080), em Configuration > Server > Log, elevando o Log Level do Server Log paraDEBUGe habilitando o Debug Level. O registro de reescrita é parte do log de depuração do servidor; sem ele ligado, não há linhas de rewrite. Atribuição: a página citada. - Para onde vai a saída: para o error log do servidor, o mesmo arquivo configurado em File Name no bloco Server Log. Em instalação cPanel o LSWS reaproveita o error log do Apache, então é lá que o trace aparece. Atribuição: a mesma página.
- Escopo: o Debug Level do Server Log é ajuste de servidor, e o quanto dele é possível restringir por vhost depende da versão do LSWS e da configuração em uso. Na prática, assuma que ligar afeta todos os sites daquela instância enquanto estiver ativo, e só quem tem root no WHM chega nesse console.
Os nomes de campo e o caminho do arquivo mudam entre versões do LSWS e do plugin de cPanel, então confira a página antes de aplicar e confirme o caminho real em File Name em vez de assumir o padrão.
Consequências práticas que valem para qualquer provedor com LSWS:
- Em hospedagem compartilhada, você não liga isso sozinho. Peça uma janela curta ao suporte, com a URL exata e o horário em que vai disparar o teste, ou reproduza o caso localmente.
- Como o efeito vale para a instância inteira, a janela precisa ser curta e combinada: tenha a URL exata e o comando
curlprontos antes de pedir. - A informação é equivalente (qual padrão foi aplicado contra qual URI, qual substituição saiu), então todo o raciocínio das seções anteriores vale. O que muda é o formato e o botão que liga.
Desligar e provar que desligou
Trace não é configuração permanente. Ele cresce o error log rápido, polui o diagnóstico de qualquer outro problema e consome CPU e I/O em cada requisição.
Reverter o LogLevel ao estado anterior
- Volte a linha ao valor anterior, aquele que você capturou com
grep -rn ... LogLevelantes de começar. Se não havia nenhuma linha no bloco, remova a linha inteira em vez de escreverLogLevel warn: assim o bloco volta a herdar o nível do pai, que é o estado original. apachectl -tpara validar a sintaxe.apachectl gracefulpara aplicar sem derrubar conexões em curso.
Confirmar pelo comportamento que o trace parou
Não confie no arquivo de configuração: confirme pelo comportamento.
# marca o tamanho atual do log
before=$(wc -c < /var/log/apache2/error.log)
# dispara a mesma URL que antes gerava trace
curl -s -o /dev/null "https://exemplo.com.br/produtos/123?trace=verifica"
# nenhuma linha de rewrite deve ter sido acrescentada
tail -c +$((before + 1)) /var/log/apache2/error.log | grep -c '\[rewrite:'
O resultado esperado é 0. Se vier diferente de zero, sobrou um LogLevel em outro escopo (um Include, um vhost de SSL duplicado, um arquivo em conf.d), e o grep -rn do passo 1 precisa ser refeito em todos os diretórios de configuração.
Sob LiteSpeed, a verificação é a mesma em espírito: desative o log de depuração pelo mesmo lugar em que foi ativado, repita a requisição e confirme que nenhuma linha nova de reescrita apareceu no error log.
Quando o log não mostra nenhuma linha de rewrite
Se depois de ligar o trace3 o error log segue sem nenhuma linha [rewrite:, o problema não é a regra. É mais cedo no caminho. Cheque nesta ordem:
- O
.htaccessestá sendo lido? Teste destrutivo: uma linha de lixo (asdf) no topo do arquivo faz o Apache responder 500. Se não vier 500, o arquivo não está sendo processado. Risco: enquanto a linha existir, toda requisição àquele diretório e aos subdiretórios responde 500, inclusive de visitantes e crawlers, e o 500 pode ser cacheado por proxy ou CDN na frente. Faça o teste em contêiner, em staging ou num subdiretório que só o seu teste acessa; em produção, só em janela combinada. Reversão: copie o arquivo antes (cp .htaccess /tmp/htaccess.bak), apague a linha imediatamente após o teste e confirme com uma requisição que volte 200 (curl -s -o /dev/null -w '%{http_code}\n' URL). Causas típicas de o arquivo não ser lido:AllowOverride Noneno diretório, caminho errado (arquivo fora do docroot efetivo), nome do arquivo com extensão escondida pelo editor, permissão que impede a leitura pelo usuário do servidor. - O
mod_rewriteestá carregado?apachectl -M | grep rewriteprecisa mostrarrewrite_module. Sem ele,RewriteEngine Onem.htaccesscostuma dar 500 por comando desconhecido, mas em algumas configurações a diretiva é simplesmente ignorada. RewriteEngine Onestá presente no escopo certo? Ele não é herdado de um.htaccessde diretório pai da forma que a maioria espera, e conjuntos de regras do pai não se aplicam ao filho quando o filho tem o próprioRewriteEngine OnsemRewriteOptions Inherit.- A resposta está vindo de antes do rewrite? Cache de página no CMS, proxy ou CDN na frente, ou um 301 já memorizado pelo navegador. Teste com
curl -Ie cabeçalhos de no-cache, nunca com a aba normal do navegador. - O escopo do
LogLevelé o do.htaccessque você quer?<Directory>com caminho que não corresponde ao diretório real (link simbólico, por exemplo) não cobre o arquivo que está rodando.
Seguindo essa ordem, ou você encontra a causa antes do rewrite, ou você chega ao par applying pattern com a URI real na mão. Nos dois casos, a fase de tentativa e erro acabou.
Referências
- Documentação oficial (litespeed) — Rewrite Logs (LiteSpeed em cPanel). Consultado em 2026-09-18.