Rozwiązywanie problemów — Dokumentacja Saplo

Build failed

"Cannot find module '...'"

Przyczyna: Brakuje zależności w package.json. Moduł jest w devDependencies, ale npm ci --production pomija je.

Fix: Przenieś brakujące moduły z devDependencies do dependencies:

// package.json - PRZED
{
  "devDependencies": {
    "some-package": "^1.0.0"
  }
}

// package.json - PO
{
  "dependencies": {
    "some-package": "^1.0.0"
  }
}

Lub jeśli chcesz instalować też devDependencies w buildzie, zmień build.install w saplo.yaml:

build:
  install: "npm ci"  # instaluje dependencies + devDependencies z package-lock.json

"pip install failed: No matching distribution found"

Przyczyna: Paczka Pythona wymaga innej wersji Pythona niż zdefiniowana w runtime.python.

Fix: Sprawdź wymagania pakietu i dostosuj wersję w saplo.yaml:

runtime:
  python: "3.11"  # zmień jeśli potrzeba

Lub zaktualizuj requirements.txt do kompatybilnej wersji paczki.

"npm run build: exit code 1" - ogólny błąd buildu

Przyczyna: Błąd w kodzie aplikacji wykryty podczas buildu (TypeScript error, ESLint, test).

Fix: Uruchom build lokalnie, żeby zobaczyć dokładny błąd:

$ npm run build

Napraw błędy i ponów saplo deploy.

"Out of memory during build"

Przyczyna: Build Node.js (np. webpack) wymaga więcej RAM niż dostępne w planie.

Fix: Zwiększ RAM przez add-on w panelu lub ogranicz zużycie pamięci przez Node:

build:
  command: "NODE_OPTIONS=--max-old-space-size=1536 npm run build"

Wartości dla różnych planów:

Box S (512 MB) - max 384 MB dla Node
Box M (2 GB) - max 1536 MB
Box L (6 GB) - max 4096 MB

"Django: No module named '...'"

Przyczyna: Moduł nie jest w requirements.txt lub jest źle zainstalowany.

Fix: Wygeneruj aktualne requirements lokalnie:

$ pip freeze > requirements.txt

Sprawdź, że wszystkie zależności produkcyjne są w pliku, i ponów deploy.

Healthcheck timeout

Aplikacja nie odpowiada na endpoint zdefiniowany w start.healthcheck w ciągu 60 sekund. Zacznij od sprawdzenia logów:

$ saplo logs --deployment <id>
# Szukaj linii: "Healthcheck: ..." lub błędów startowych

Zmiana endpointu healthcheck

Zmień endpoint na prostszy lub wyłącz healthcheck tymczasowo:

start:
  healthcheck: "/"  # zamiast /api/health

Wyłączenie healthchecka (healthcheck: ~) nie jest zalecane - Saplo nie wykryje wtedy nieudanego startu aplikacji.

Dodanie endpointu /api/health

Next.js - plik app/api/health/route.ts:

export async function GET() {
  return Response.json({ status: 'ok' })
}

Django - urls.py:

from django.http import JsonResponse

def health(request):
    return JsonResponse({'status': 'ok'})

urlpatterns = [
    path('health/', health),
    ...
]

Aplikacja startuje wolno (baza danych, heavy init)

Przyczyna: Inicjalizacja (połączenie do bazy, ładowanie modeli ML, kompilacja JIT) trwa dłużej niż 60 s.

Zwiększ timeout healthchecka przez support (domyślnie 60 s, max 300 s). Lub przyspiesz start aplikacji - nie ładuj dużych zasobów synchronicznie przy starcie.

Zmienne środowiskowe

Zmienna @secret nie działa - deploy zwraca błąd

Przyczyna: Zmienna jest zdefiniowana jako @secret w saplo.yaml, ale jej wartość nie została ustawiona przez saplo env set.

$ saplo env list
# Sprawdź czy DATABASE_URL jest na liście

$ saplo env set DATABASE_URL="postgresql://user:pass@host:5432/db"
$ saplo deploy

Zmienne środowiskowe są puste w aplikacji

Przyczyna 1: W React/Vite - zmienne build-time muszą mieć prefix VITE_ (Vite) lub REACT_APP_ (CRA) i są dostępne tylko podczas buildu.

Przyczyna 2: Zmienna została dodana po ostatnim deployu - efekty wejdą w życie dopiero po ponownym deployu.

$ saplo env set VITE_API_URL="https://api.example.com"
$ saplo deploy  # wymagany nowy deploy

Certyfikat SSL / domena

SSL w stanie "pending" - certyfikat się nie generuje

Przyczyna: Rekord DNS nie zdążył się spropagować lub jest błędny.

# Sprawdź czy DNS wskazuje na Saplo
$ dig +short example.pl A
# Powinno zwrócić: 116.202.174.87

# Sprawdź z zewnętrznego DNS
$ dig +short example.pl A @1.1.1.1

Jeśli rekord jest błędny:

Dodaj rekord A example.pl -> 116.202.174.87 u swojego dostawcy DNS.
Poczekaj 5-60 min na propagację.
SSL zostanie wydany automatycznie po propagacji.

Jeśli DNS się spropagował, ale SSL nadal jest w stanie pending - skontaktuj się z supportem: support@saplo.pl.

Błąd "NET::ERR_CERT_AUTHORITY_INVALID" w przeglądarce

Przyczyna: Let's Encrypt nie mógł zweryfikować domeny (rate limit, błąd ACME challenge).

$ dig +short example.pl
# Musi być: 116.202.174.87

Jeśli DNS wskazuje poprawnie, poczekaj do 10 minut (automatyczny retry ACME challenge). Jeśli problem trwa, skontaktuj się z supportem.

Autoryzacja i tokeny API

Błąd 401 Unauthorized / "Token revoked"

Przyczyna: Token API został unieważniony lub wygasł.

Wygeneruj nowy token: panel - Ustawienia - API Tokens - Nowy token. Następnie zaktualizuj go w CLI:

$ saplo login --token saplo_live_<nowy_token>

W CI/CD (GitHub Actions) zaktualizuj secret SAPLO_TOKEN w ustawieniach repozytorium.

Inne problemy

Aplikacja nie startuje - konflikt portów

Przyczyna: Port zdefiniowany w start.port jest już zajęty przez inny proces.

Zmień port w saplo.yaml i komendzie startowej - muszą być zgodne:

start:
  command: "node server.js --port 3001"
  port: 3001

Upload bardzo wolny przy saplo deploy

Przyczyna: node_modules lub inne duże katalogi nie są wykluczone z paczki deployowej.

Utwórz plik .saploignore w katalogu projektu:

node_modules
.next/cache
dist/cache
.git
*.log
coverage
.venv
__pycache__

Sprawdź rozmiar paczki przed uploadem:

$ saplo deploy --dry-run
# Wyświetla rozmiar bez uploadu (zaplanowane)

Django: "CSRF verification failed"

Przyczyna: Django CSRF middleware blokuje requesty przez proxy NPM.

Dodaj do settings.py:

CSRF_TRUSTED_ORIGINS = [
    'https://my-app.saploapp.pl',
    'https://example.pl',
]

Kontakt z supportem

Jeśli problem nadal występuje, skontaktuj się z nami. Do zgłoszenia dołącz app_id, deployment_id (z saplo logs --list), logi deploymentu i opis kroków reprodukcji.

Email: support@saplo.pl
Panel: zakładka "Support" - Nowy ticket
Priority support (SLA 1h): add-on dostępny w panelu