Como Resolver o Erro “OCI runtime create failed” no Docker [Guia Atualizado 2026]

スポンサーリンク

Como Resolver o Erro “OCI runtime create failed” no Docker [Guia Atualizado 2026]

Está recebendo a mensagem “Error response from daemon: OCI runtime create failed” ao tentar iniciar um contêiner Docker? Este artigo fornece um guia completo e atualizado para 2026 sobre as causas e soluções específicas para este erro. Seja você iniciante ou usuário avançado, este guia passo a passo ajudará a resolver o problema.

O Que É Este Erro? Sintomas que Você Experimentará

O erro “OCI runtime create failed” indica que o runtime de contêineres de baixo nível do Docker, o runc, não conseguiu iniciar o processo do contêiner. OCI (Open Container Initiative) é uma organização industrial que define padrões de contêineres, e o Docker utiliza um runtime compatível com OCI para gerenciar contêineres.

Quando este erro ocorre, seu terminal exibirá mensagens como:

docker: Error response from daemon: OCI runtime create failed:
container_linux.go:380: starting container process caused: exec: "python":
executable file not found in $PATH: unknown.

Ou:

Error response from daemon: failed to create shim: OCI runtime create failed:
runc create failed: unable to start container process: error during container init:
error mounting "proc" to rootfs at "/proc": permission denied

Quando este erro ocorre, seu contêiner não iniciará de forma alguma. O comando docker run retorna um erro imediatamente, tornando impossível acessar qualquer aplicação dentro do contêiner. Este erro pode ocorrer não apenas em ambientes de desenvolvimento, mas também em pipelines de CI/CD em produção (CircleCI, GitHub Actions, etc.) e em clusters Kubernetes, bloqueando completamente os deploys.

O que torna este erro particularmente frustrante é que a mensagem de erro é longa e complexa, dificultando a identificação da causa raiz à primeira vista. No entanto, a pista chave está escondida na parte após “caused:” na mensagem de erro. Este artigo explica como interpretar essas pistas e fornece soluções para cada padrão.

Causas Deste Erro

O erro “OCI runtime create failed” tem cinco causas principais. Compreender cada padrão ajudará a identificar rapidamente o problema a partir da mensagem de erro.

Causa 1: Arquivo Executável Não Encontrado (executable file not found in $PATH)

Esta é uma das causas mais comuns. Ocorre quando o executável especificado no ENTRYPOINT ou CMD do Dockerfile não existe no $PATH da imagem do contêiner. Casos específicos incluem:

  • Erros de digitação no nome do comando (por exemplo, escrever pytohn em vez de python)
  • A imagem base não inclui o comando necessário (por exemplo, bash não está incluído em imagens alpine)
  • Esquecer de copiar binários para a imagem final em builds multi-estágio
  • Configuração incorreta de WORKDIR impedindo a resolução de caminhos de scripts

Causa 2: Problemas de Permissão (permission denied)

Ocorre quando o processo de inicialização do contêiner não possui as permissões necessárias para acessar arquivos ou diretórios. Casos comuns incluem:

  • O script de entrypoint não tem permissões de execução (chmod +x)
  • SELinux ou AppArmor na máquina host está bloqueando o acesso a arquivos do contêiner
  • Rotulagem inadequada de volumes montados por bind
  • Propriedade de arquivos corrompida sob /var/lib/docker

Causa 3: Versões Desatualizadas do Docker ou runc

Versões antigas do Docker Engine, containerd ou runc podem causar problemas de compatibilidade com recursos mais recentes do kernel. Em particular, versões do Docker abaixo de 25 foram relatadas como problemáticas em distribuições Linux recentes. A compatibilidade também pode ser quebrada após atualizações do sistema operacional host (por exemplo, Proxmox VE 8.1 para 8.2).

Causa 4: Problemas de Compatibilidade com cgroup v2

Distribuições Linux recentes (Ubuntu 22.04+, Fedora 31+, etc.) têm cgroup v2 habilitado por padrão. Versões antigas do Docker ou runc que não suportam cgroup v2 produzirão erros como:

OCI runtime create failed: runc create failed: unable to start container process:
error during container init: error setting cgroup config for procHooks process

cgroup v2 requer kernel 4.15 ou superior (recomendado 5.2+).

Causa 5: Esgotamento de Espaço em Disco e Conflitos de Recursos

Quando imagens e contêineres Docker esgotam o espaço disponível em disco, este erro aparece com a mensagem no space left on device. Conflitos com portas ou diretórios já em uso também podem causar este erro.

Solução 1: Interpretar Mensagens de Erro e Corrigir Problemas com Executáveis (Recomendado)

A abordagem mais importante e eficaz é interpretar corretamente a mensagem de erro. Para este erro, a razão específica da falha é indicada após caused:.

Passo 1: Analisar a Mensagem de Erro

Primeiro, examine cuidadosamente a mensagem de erro. Aqui está a estrutura típica:

Error response from daemon: OCI runtime create failed:
container_linux.go:380: starting container process caused:
exec: "python": executable file not found in $PATH: unknown

Neste caso, após caused:, diz exec: "python": executable file not found in $PATH. Isso significa que o comando “python” não foi encontrado no PATH do contêiner.

Passo 2: Verificar e Corrigir o Dockerfile

Se o erro está relacionado a arquivos executáveis, verifique seu Dockerfile:

# Exemplo incorreto: imagem alpine não inclui python
FROM alpine:latest
CMD ["python", "app.py"]

# Exemplo correto: usar a imagem oficial do Python
FROM python:3.12-slim
COPY app.py /app/
WORKDIR /app
CMD ["python", "app.py"]

Para erros de bash não encontrado (comuns com imagens baseadas em Alpine Linux):

# Exemplo incorreto
RUN /bin/bash -c "echo hello"

# Exemplo correto: Alpine inclui ash por padrão
RUN /bin/sh -c "echo hello"

# Ou instalar o bash
RUN apk add --no-cache bash

Passo 3: Verificar Arquivos Dentro do Contêiner

Você pode iniciar a imagem interativamente para verificar a existência de arquivos:

# Entrar no contêiner com um shell especificado
docker run --rm -it --entrypoint /bin/sh myimage:latest

# Verificar comandos no PATH
which python
echo $PATH
ls -la /app/

Notas Importantes

  • Se usar builds multi-estágio, verifique se todos os binários necessários foram copiados para o estágio final
  • Se ENTRYPOINT e CMD estão ambos configurados, verifique como se combinam (forma exec vs forma shell)
  • Verifique se as instruções COPY copiam corretamente os arquivos e se .dockerignore não os exclui

Solução 2: Corrigir Permissões e Políticas de Segurança

Se a mensagem de erro contém “permission denied”, o problema está relacionado a permissões ou políticas de segurança.

Conceder Permissões de Execução ao Script de Entrypoint

# Conceder permissões de execução localmente
chmod +x entrypoint.sh

# Conceder permissões no Dockerfile
COPY entrypoint.sh /app/
RUN chmod +x /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]

Tratamento em Ambientes SELinux

Em ambientes com SELinux habilitado (RHEL, CentOS, Fedora, etc.), políticas podem bloquear o acesso do contêiner a arquivos do host.

# Verificar o status do SELinux
sestatus

# Verificar logs de negação do SELinux
sudo ausearch -m avc -ts recent

# Método 1: Adicionar sufixo :z ou :Z ao montar volumes (recomendado)
docker run -v /host/data:/container/data:z myapp:latest

# Método 2: Desabilitar rótulos SELinux para depuração (não recomendado para produção)
docker run --security-opt label=disable myapp:latest

O sufixo :z torna o volume compartilhável entre múltiplos contêineres, enquanto :Z o rotula exclusivamente para aquele contêiner. Sempre use :z ou :Z em produção e evite label=disable.

Tratamento em Ambientes AppArmor

Problemas similares podem ocorrer com AppArmor no Ubuntu e outros sistemas. Notavelmente, desde o patch de segurança containerd.io 1.7.28-2 em novembro de 2025, erros relacionados ao AppArmor aumentaram ao executar Docker dentro de contêineres LXC aninhados.

# Desabilitar perfil AppArmor para depuração (não recomendado para produção)
docker run --security-opt apparmor=unconfined myapp:latest

# Verificar o status do AppArmor
sudo aa-status

Corrigir Propriedade de Arquivos

# Verificar a propriedade de /var/lib/docker
ls -la /var/lib/docker/

# Reiniciar o daemon do Docker se necessário
sudo systemctl restart docker

Solução 3: Atualizar Docker/runc e Corrigir Configurações de cgroup (Avançado)

Problemas de compatibilidade de versão e configuração do kernel exigem correções de nível mais profundo.

Atualizar Docker Engine

Atualizar para Docker 25 ou superior resolve muitos problemas de compatibilidade.

# Verificar a versão atual do Docker
docker version

# Para Ubuntu/Debian: atualizar do repositório oficial do Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Para CentOS/RHEL
sudo yum update docker-ce docker-ce-cli containerd.io

Atualizar runc Separadamente

Você também pode atualizar o runc independentemente:

# Verificar a versão do runc
runc --version

# Instalar a versão mais recente do runc a partir das releases do GitHub
wget https://github.com/opencontainers/runc/releases/download/v1.2.5/runc.amd64
sudo install -m 755 runc.amd64 /usr/local/sbin/runc

Resolver Compatibilidade com cgroup v2

Se você está experimentando erros relacionados ao cgroup v2:

# Verificar a versão atual do cgroup
stat -fc %T /sys/fs/cgroup/
# "cgroup2fs" significa que v2 está habilitado

# Verificar a versão do kernel (recomendado 5.2+)
uname -r

Método A: Modificar a configuração do daemon do Docker

# Editar /etc/docker/daemon.json
sudo tee /etc/docker/daemon.json <<EOF
{
  "default-cgroupns-mode": "host",
  "exec-opts": ["native.cgroupdriver=systemd"]
}
EOF

# Reiniciar o Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

Método B: Voltar para cgroup v1 (não recomendado, mas eficaz em emergências)

Adicione o seguinte aos parâmetros de boot do GRUB para forçar cgroup v1:

# Editar /etc/default/grub
GRUB_CMDLINE_LINUX="systemd.unified_cgroup_hierarchy=0"

# Atualizar GRUB e reiniciar
sudo update-grub
sudo reboot

Verificar e Liberar Espaço em Disco

# Verificar espaço em disco usado pelo Docker
docker system df

# Remover todas as imagens, contêineres e volumes não utilizados
docker system prune -a --volumes

# Remover imagens pendentes
docker image prune

Verificar Configuração do Serviço systemd

Em alguns ambientes, a configuração do arquivo de unidade systemd do Docker pode causar problemas:

# Verificar o arquivo de unidade do serviço Docker
sudo systemctl cat docker.service

# Se MountFlags=slave estiver configurado, remova
sudo systemctl edit docker.service
# [Service]
# MountFlags=

# Aplicar alterações
sudo systemctl daemon-reload
sudo systemctl restart docker

Como Prevenir Este Erro

Siga estas melhores práticas para prevenir o erro “OCI runtime create failed”.

1. Seguir as Melhores Práticas de Dockerfile

  • Usar imagens oficiais como base
  • Em builds multi-estágio, verificar se o estágio final contém todos os arquivos necessários
  • Compreender e usar corretamente a diferença entre ENTRYPOINT e CMD
  • Configurar adequadamente o arquivo .dockerignore

2. Testar Exaustivamente Localmente

# Testar se a imagem construída inicia corretamente
docker build -t myapp:test .
docker run --rm myapp:test

3. Manter o Ambiente Docker Atualizado

Atualize regularmente Docker Engine, containerd e runc. Aplique prontamente atualizações menores contendo patches de segurança.

4. Monitorar o Espaço em Disco Regularmente

# Verificar periodicamente o uso do disco
docker system df
# Limpeza regular de recursos não utilizados
docker system prune -f --filter "until=168h"

5. Fixar Versões do Docker em Pipelines CI/CD

Ao usar Docker em CI/CD, fixe a versão do Docker para prevenir problemas de compatibilidade inesperados.

Resumo

O erro “OCI runtime create failed” do Docker pode parecer complexo, mas ao ler cuidadosamente a parte após caused: na mensagem de erro, identificar a causa raiz é relativamente simples.

Pontos-chave:

  1. Executável não encontrado → Verifique ENTRYPOINT/CMD no Dockerfile e especifique o caminho e comando corretos
  2. Erros de permissão → Verifique as permissões de execução do script e as configurações do SELinux/AppArmor
  3. Problemas de compatibilidade de versão → Atualize Docker, runc e kernel para a versão mais recente
  4. Problemas relacionados a cgroup → Ajuste as configurações de cgroup no daemon.json
  5. Problemas de espaço em disco → Limpe recursos desnecessários com docker system prune

Se os métodos deste artigo não resolverem seu problema, tente:

  • Publicar uma pergunta no Docker Community Forums (forums.docker.com)
  • Pesquisar issues no repositório GitHub moby/moby
  • Perguntar no Stack Overflow com a saída de docker info e docker version

Copiar a mensagem de erro completa e pesquisá-la é o primeiro passo mais eficiente para a resolução.

Referências

コメント

タイトルとURLをコピーしました