.. _solucao_problemas:

====================
Solução de Problemas
====================

.. contents:: Nesta seção:
   :local:
   :depth: 2

Esta seção fornece soluções para problemas comuns encontrados por usuários do GridUnesp. Os problemas estão organizados por categoria para facilitar a consulta.

.. tip::
   Antes de contatar o suporte, consulte esta seção. A maioria dos problemas já possui solução documentada.

Problemas de Acesso
===================

Erro de Autenticação SSH
------------------------

**Sintoma:** Ao tentar conectar, aparece "Permission denied" ou erro de autenticação.

**Soluções possíveis:**

1. **Verifique suas credenciais**

   .. code-block:: bash
      :caption: Teste de conexão com debug

      ssh -vvv username@access.grid.unesp.br

   - Certifique-se de que está usando o **username correto**
   - Verifique se a **senha está correta** (sem Caps Lock)
   - Se esqueceu a senha, reset em: https://www.ncc.unesp.br/password-new/


2. **Verifique a chave SSH do servidor**

   As chaves corretas do servidor access.grid.unesp.br são:

   .. code-block:: text

      RSA:     SHA256:X3iCb13fWj7u2Tvp/MCCpn0brfSNS5Ie6ehm6lsvPSQ
      ECDSA:   SHA256:WVFokXOLnuH9+2e7xxRU2gp7XJqxwuE6H8bbUMqTCXo
      ED25519: SHA256:+HEvFMmo0EA6ipPMJSaj5+Q6IabebRN+nRD0nxdYrKQ

   Se a chave no seu sistema não corresponder, remova a entrada antiga:

   .. code-block:: bash

      ssh-keygen -f "~/.ssh/known_hosts" -R "access.grid.unesp.br"

3. **Verifique bloqueios de rede**

   - Porta 22 (SSH) deve estar liberada
   - Firewalls corporativos podem bloquear
   - Redes com proxy podem necessitar configuração especial

Conexão Recusada (Connection Refused)
-------------------------------------

**Sintoma:** ``ssh: connect to host access.grid.unesp.br port 22: Connection refused``

**Causa provável:** Bloqueio pelo sistema **Fail2Ban** após múltiplas tentativas de login com senha incorreta ou uso excessivo de SCP.

**Solução:**

- Aguarde **15 minutos** e tente novamente
- Não tente repetidamente durante o bloqueio (reinicia o contador)
- Se persistir, envie a saída do comando abaixo para o suporte:

  .. code-block:: bash

     ssh -vvv username@access.grid.unesp.br

Conexão Lenta ou Instável
-------------------------

**Sintomas:**

- Comandos demoram para responder
- Conexão cai frequentemente
- Latência alta

**Soluções:**

1. **Use compressão SSH:**

   .. code-block:: bash

      ssh -C username@access.grid.unesp.br

2. **Mantenha a conexão ativa:**

   .. code-block:: bash
      :caption: Configuração no ~/.ssh/config

      Host access.grid.unesp.br
          ServerAliveInterval 60
          ServerAliveCountMax 3

3. **Use screen ou tmux** para sessões persistentes:

   .. code-block:: bash

      screen -S sessao_grid
      # Dentro do screen, faça o login normal
      # Para desconectar: Ctrl+A, depois D
      # Para reconectar: screen -r sessao_grid

4. **Verifique sua conexão de internet** (velocidade, latência, perda de pacotes)

Problemas com Jobs
==================

Job em Estado PENDING por Muito Tempo
-------------------------------------

**Sintoma:** ``squeue`` mostra seu job com estado **PD** (Pending) por horas ou dias.

**Causas possíveis:**

1. **Falta de recursos disponíveis**

   Verifique o estado do cluster:

   .. code-block:: bash

      sinfo                     # Visão geral dos nós
      squeue -r | wc -l         # Total de jobs
      squeue -r -t PD | wc -l   # Jobs pendentes

2. **Recursos solicitados inviáveis**

   Verifique se você não solicitou mais do que o disponível:

   - Máximo de 52 CPUs por nó (nó de CPU)
   - Máximo de 88 CPUs no nó de GPU
   - Máximo de 30 dias de execução
   - Memória compatível com o solicitado

3. **Prioridade baixa**

   O sistema utiliza política de Fair Share:

   .. code-block:: bash

      sprio -u $USER             # Ver prioridade do seu job
      squeue -o "%.18i %.9Q %.8j %.8u %.10V %.6D %R" --sort=-p,i --states=PD

4. **Partição incorreta**

   Verifique as partições disponíveis:

   .. code-block:: bash

      sinfo -o "%9P %5a %10l %6D %6t %N"

**Soluções:**

- Aguarde (períodos de pico podem ter filas longas)
- Reduza recursos solicitados (menos CPUs, menos tempo)
- Submeta em horários de menor demanda (madrugada, finais de semana)
- Divida em jobs menores (job array)

Job Falha Imediatamente
-----------------------

**Sintoma:** Job entra em execução mas falha em poucos segundos (estado **F** ou **FAILED**).

**Diagnóstico:**

1. **Verifique o arquivo de saída:**

   .. code-block:: bash

      cat slurm-JOBID.out
      tail -50 slurm-JOBID.out

2. **Verifique o arquivo de erro (se especificado):**

   .. code-block:: bash

      cat slurm-JOBID.err

3. **Verifique o status detalhado:**

   .. code-block:: bash

      scontrol show job JOBID

**Problemas comuns e soluções:**

==================== =============================================== ======================================
**Erro**             **Causa**                                       **Solução**
-------------------- ----------------------------------------------- --------------------------------------
"INPUT is missing"   Variável INPUT não definida                     Adicione ``export INPUT="..."``
"OUTPUT is missing"  Variável OUTPUT não definida                    Adicione ``export OUTPUT="..."``
"command not found"  Módulo não carregado                            Adicione ``module load ...`` 
"Permission denied"  Arquivo sem permissão de execução               ``chmod +x programa``
"Segmentation fault" Erro no código ou memória insuficiente          Aumente memória, debug código
"Out of memory"      Programa consumiu mais memória que o solicitado Aumente ``--mem`` ou ``--mem-per-cpu``
==================== =============================================== ======================================

Job Cancelado (CANCELLED)
-------------------------

**Sintoma:** Job aparece como **CANCELLED** no histórico.

**Causas:**

1. **TIMEOUT:** Job excedeu o tempo solicitado

   .. code-block:: bash

      sacct -j JOBID --format=JobID,State,ExitCode,Elapsed,Timelimit

   **Solução:** Aumente ``#SBATCH -t`` ou otimize o código.

2. **Cancelamento manual:**

   - Você pode ter cancelado com ``scancel JOBID``
   - Administradores podem ter cancelado

3. **Falha no nó de processamento:**

   - Falha de hardware detectada
   - Nó reiniciado ou em manutenção

   **Solução:** Resubmeta o job (será alocado em outro nó).

4. **Uso excessivo no servidor access:**

   - Jobs pesados executados no access são cancelados pelos administradores.

   **Solução:** Sempre use ``sbatch`` para submeter aos nós de processamento.

Job com Erro de Biblioteca
--------------------------

**Sintoma:** "error while loading shared libraries" ou "cannot find -lname".

**Diagnóstico:**

.. code-block:: bash

   ldd ./seu_executavel          # Mostra dependências
   module list                   # Ver módulos carregados

**Soluções:**

1. **Carregue o módulo correto:**

   .. code-block:: bash

      module avail nome_parcial   # Buscar biblioteca
      module load nome_biblioteca

2. **Configure LD_LIBRARY_PATH** (se instalou localmente):

   .. code-block:: bash

      export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/local/lib

3. **Recompile o programa** com as bibliotecas corretas

Problemas de Compilação
-----------------------

**Sintoma:** Erros durante compilação com ``make``, ``gcc``, etc.

**Soluções:**

1. **Verifique os compiladores disponíveis:**

   .. code-block:: bash

      module avail gcc
      module avail intel

2. **Carregue o compilador desejado:**

   .. code-block:: bash

      module load gcc/9.3.0
      # ou
      module load intel/2020

3. **Para aplicações MPI, carregue também o módulo MPI:**

   .. code-block:: bash

      module load openmpi/4.0.1
      # ou
      module load intel/mpi/2017

4. **Instale dependências faltantes:**

   - Bibliotecas de desenvolvimento
   - Headers necessários

5. **Configure flags de compilação adequadas:**

   .. code-block:: bash

      CFLAGS="-O2 -march=native" ./configure --prefix=$HOME/local
      make
      make install

Problemas de Armazenamento
==========================

Sem Espaço em Disco
-------------------

**Sintoma:** Erro "No space left on device" ou "Disk quota exceeded".

**Diagnóstico:**

.. code-block:: bash
   :caption: Verificar uso de espaço

   df  -h /home               # Espaço total em /home/
   du -sh /home/$USER         # Total usado pelo usuário
   du -sh /home/$USER/* | sort -hr | head -20   # Maiores diretórios

   # Verificar /store/ (se aplicável)
   du -sh /store/$USER/* | sort -hr | head -20

**Soluções:**

1. **Remova arquivos desnecessários:**

   .. code-block:: bash

      rm slurm-*.out                   # Logs antigos
      rm -rf diretorios_temporarios/   # Diretórios temporários

2. **Comprima arquivos grandes:**

   .. code-block:: bash

      tar -czf resultados.tar.gz diretorio_resultados/
      rm -rf diretorio_resultados/      # Após confirmar que o tar está OK

3. **Transfira dados importantes** para seu computador local

4. **Use /store/ para arquivos temporários grandes** durante execução:

   .. code-block:: bash

      export SHARED_FS="true"

.. warning::
   **Não há quotas de disco** no GridUnesp, mas o espaço é compartilhado. O acúmulo excessivo prejudica todos os usuários.

Arquivos Desapareceram
----------------------

**Sintoma:** Arquivos que estavam no diretório não são mais encontrados.

**Causas possíveis:**

1. **Limpeza automática do /tmp/**

   - Arquivos em ``/tmp/`` dos nós são apagados após o job
   - Certifique-se de que usou ``job-nanny`` com OUTPUT definido

2. **Exclusão acidental**

   - Comandos como ``rm -rf`` podem ter sido usados incorretamente
   - Verifique histórico de comandos com ``history | grep rm``

3. **Falha no storage**

   - Falhas de hardware podem causar corrupção/perda
   - O GridUnesp **não possui backup automático**

.. danger::
   **O GridUnesp NÃO faz backup automático dos dados.**
   
   Dados perdidos por falha de hardware **não podem ser recuperados**.

**Prevenção:**

- Mantenha backups de dados importantes em seu computador local
- Use versionamento (git) para scripts e código
- Transfira resultados críticos assim que o job terminar

Erro de Permissão
-----------------

**Sintoma:** "Permission denied" ao acessar arquivos ou diretórios.

**Diagnóstico:**

.. code-block:: bash

   ls -la arquivo           # Ver permissões atuais
   id                       # Ver seu UID/GID

**Soluções:**

1. **Ajuste permissões:**

   .. code-block:: bash

      chmod +r arquivo.dat              # Adicionar leitura
      chmod +x script.sh                # Adicionar execução
      chmod -R g+rw diretorio/          # Leitura/escrita para grupo

2. **Verifique propriedade:**

   .. code-block:: bash

      chown $USER:$USER arquivo          # Tornar-se proprietário

3. **Para compartilhar com colegas:**

   .. code-block:: bash

      chmod g+rx diretorio/              # Grupo pode ler/executar
      chmod o-rwx diretorio/             # Outros não têm acesso

Problemas de Performance
========================

Job Muito Lento
---------------

**Sintoma:** Job demora mais que o esperado para executar.

**Causas e soluções:**

1. **Uso inadequado de recursos**

   - Verifique se o job está usando todos os recursos solicitados:

     .. code-block:: bash

        sstat --format=JobID,MaxRSS,MaxVMSize,AveCPU -j JOBID.batch
        sstat --format=JobID,MaxRSS,MaxVMSize,AveCPU -j 23134.batch
        sstat --format=JobID,MaxRSS,MaxVMSize,AveCPU -j JOBID -a
        sstat --format=JobID,MaxRSS,MaxVMSize,AveCPU -j 23134 -a


   - Ajuste número de threads/processos no código

2. **I/O intensivo**

   - Muitas operações de leitura/escrita em disco
   - Considere usar ``/tmp/`` (mais rápido) para arquivos temporários
   - Minimize operações de I/O (leia uma vez, processe, escreva uma vez)

3. **Gargalo de memória**

   - Cache insuficiente, levando a swapping
   - Aumente memória disponível com ``#SBATCH --mem=...``

4. **Código não otimizado**

   - Use flags de otimização na compilação (``-O2``, ``-O3``)
   - Revise algoritmos (complexidade, estruturas de dados)
   - Paralelize onde possível (OpenMP, MPI)

5. **Concorrência com outros jobs**

   - Recursos compartilhados (storage, rede) podem estar saturados
   - Tente executar em horários de menor demanda

Uso Excessivo de Memória (OOM)
-------------------------------

**Sintoma:** Job é morto com "Out of Memory" ou "Killed".

**Diagnóstico:**

.. code-block:: bash

   sacct -j JOBID --format=JobID,ReqMem,MaxRSS,State
   # ReqMem: memória solicitada
   # MaxRSS: memória máxima realmente usada

**Soluções:**

1. **Aumente a memória solicitada:**

   .. code-block:: bash

      #SBATCH --mem=16G          # 16 GB por nó
      # or
      #SBATCH --mem-per-cpu=4G   # 4 GB por CPU

2. **Otimize o uso de memória do programa:**

   - Libere memória não utilizada
   - Processe em lotes (batch) em vez de tudo na memória
   - Use estruturas de dados mais eficientes

3. **Reduza o problema** (processe partes separadamente)

4. **Use algoritmos com menor pegada de memória**

Problemas com Módulos
=====================

Módulo Não Encontrado
---------------------

**Sintoma:** "module: command not found" ou "module load nome" falha.

**Soluções:**

1. **Verifique se o ambiente de módulos está inicializado:**

   .. code-block:: bash

      which module
      module --version

   Se não estiver disponível, o sistema pode estar com problema - contate o suporte.

2. **Liste módulos disponíveis:**

   .. code-block:: bash

      module avail                 # Todos os módulos
      module avail nome_parcial    # Busca por nome parcial

3. **Verifique se o módulo existe com o nome correto:**

   - Case sensitive (OpenMPI ≠ openmpi)
   - Versões específicas (gcc/9.3.0 ≠ gcc)

Conflito entre Módulos
----------------------

**Sintoma:** Ao carregar um módulo, outro é automaticamente descarregado.

**Causa:** Módulos incompatíveis entre si (ex: diferentes versões de MPI).

**Soluções:**

1. **Use ambientes separados:**

   .. code-block:: bash

      module purge                  # Descarrega todos
      module load openmpi/4.0.1     # Carrega apenas o necessário

   .. warning::
      O script ``job-nanny`` é reconhecido ao carregar o módulo **gridunesp**.
      
      Quando o usuário faz login no cluster, esse módulo é carregado automaticamente.
      
      Caso tenha usado o comando ``module purge``, é preciso fazer
     
      .. code-block:: bash

         module load gridunesp
         
      para que o ``job-nanny`` esteja disponível.

      Ver seção :ref:`script_job_nanny`.

2. **Verifique dependências:**

   .. code-block:: bash

      module show nome_modulo       # Mostra dependências e conflitos

3. **Use module swap** para trocar versões:

   .. code-block:: bash

      module swap gcc gcc/9.3.0

Problemas com job-nanny
=======================

INPUT/OUTPUT Obrigatórios
-------------------------

**Sintoma:** Job cancelado com erro sobre INPUT/OUTPUT.

**Causa:** O script ``job-nanny`` exige a definição das variáveis de ambiente INPUT e OUTPUT.

**Solução:**

.. code-block:: bash
   :caption: Exemplo correto

   #!/bin/bash
   #SBATCH -J meu_job

   # Havendo mais de um entrada,
   # separe os nomes por espaço em branco   
   export INPUT="dados_entrada.dat parametros.txt"
   export OUTPUT="resultados_saida.dat logs/"
   
   module load meu_software
   job-nanny ./meu_programa

Uso de /store/ vs /tmp/
------------------------

**Sintoma:** Job lento ou com problemas de espaço.

**Solução:** Escolha o local adequado:

.. code-block:: bash
   :caption: Forçar uso de /store/ (para arquivos grandes)

   export SHARED_FS="true"    # Usa /store/
   # ou
   export LARGE_FILES="true"  # Mesmo efeito

.. code-block:: bash
   :caption: Forçar uso de /tmp/ (padrão para 1 nó)

   export SHARED_FS="false"   # Usa /tmp/ (apenas para 1 nó)

.. note::
   Com múltiplos nós (``-N >1``), o uso de ``/store/`` é automático e não pode ser alterado.

Problemas de Rede
=================

Transferência Lenta
-------------------

**Sintoma:** SCP/RSYNC muito lentos.

**Soluções:**

1. **Use compressão:**

   .. code-block:: bash

      scp -C arquivo.dat usuario@access.grid.unesp.br:~/

2. **Use RSYNC (mais eficiente para diretórios):**

   .. code-block:: bash

      rsync -avz diretorio/ usuario@access.grid.unesp.br:~/diretorio/

3. **Compacte antes de transferir:**

   .. code-block:: bash

      tar -czf dados.tar.gz diretorio/
      scp dados.tar.gz usuario@access.grid.unesp.br:~/

4. **Evite horários de pico**. Utilize o período da noite ou fins de semana.

Falha na Transferência
----------------------

**Sintoma:** Transferência interrompida no meio.

**Soluções:**

1. **Use RSYNC (permite retomar):**

   .. code-block:: bash

      rsync -avz --partial --progress arquivo.dat usuario@access.grid.unesp.br:~/

2. **Divida arquivos grandes:**

   .. code-block:: bash

      split -b 1G arquivo_grande.dat parte_   # Divide em partes de 1GB
      # Transfira as partes
      cat parte_* > arquivo_grande.dat        # Remonta no destino

3. **Use screen/tmux** para evitar que a transferência morra ao fechar o terminal

Problemas Gerais
================

Comando Não Encontrado
----------------------

**Sintoma:** "command not found" para comandos comuns.

**Soluções:**

1. **Verifique o PATH:**

   .. code-block:: bash

      echo $PATH
      which nome_comando

2. **Comandos comuns podem não estar disponíveis** - use caminho completo:

   .. code-block:: bash

      /usr/bin/nome_comando
      /bin/nome_comando

3. **Instale localmente** se for um programa específico. Ver seção :ref:`instalando_aplicacoes`.

Shell Padrão
------------

**Sintoma:** Prefere outro shell (zsh, fish, etc.) mas o padrão é bash.

**Solução:** Altere seu shell padrão:

.. code-block:: bash

   chsh -s /bin/zsh          # Exemplo para zsh
   # Faça logout e login novamente

.. note::
   Nem todos os shells estão disponíveis. O padrão é bash.

Idioma do Sistema
-----------------

**Sintoma:** Mensagens em inglês, prefere português.

**Solução:** Configure a variável de ambiente:

.. code-block:: bash

   export LANG=pt_BR.UTF-8
   export LANGUAGE=pt_BR

Para tornar permanente, adicione ao ``~/.bashrc``.

Quando Contatar o Suporte
=========================

Se após tentar as soluções acima o problema persistir:

**Prepare as seguintes informações:**

1. **Descrição clara do problema**
2. **Seu username**
3. **IDs dos jobs** (se aplicável)
4. **Caminho completo dos scripts e arquivos**
5. **Conteúdo dos arquivos de log** (slurm-JOBID.out)
6. **Comandos executados** e suas saídas
7. **Tentativas de solução** já realizadas

**Envie para:** ``support.ncc@unesp.br``

.. tip::
   Quanto mais completo for seu relato, mais rápida e precisa será a resposta.

.. seealso::

   - :ref:`perguntas_frequentes` - Dúvidas comuns
   - :ref:`boas_praticas` - Recomendações de uso
   - :ref:`contato` - Canais de suporte