Przewodnik rozwiązywania problemów

Ten przewodnik dostarcza rozwiązania typowych problemów technicznych, komunikatów błędów i problemów konfiguracyjnych, które możesz napotkać podczas używania Cursor, Claude Code i serwerów MCP.

Problemy z Cursor

Problemy z instalacją i konfiguracją

Cursor nie uruchamia się po instalacji

Sprawdź wymagania systemowe
- macOS 10.15+, Windows 10+, lub Linux (64-bit)
- Przynajmniej 4GB RAM (zalecane 8GB)
- 2GB wolnego miejsca na dysku
Spróbuj trybu bezpiecznego
Okno terminala
```
cursor --disable-extensions
```
Zresetuj dane użytkownika (najpierw zrób kopię zapasową!)
- Windows: %APPDATA%\Cursor
- macOS: ~/Library/Application Support/Cursor
- Linux: ~/.config/Cursor
Sprawdź konfliktujące oprogramowanie
- Antywirus blokujący wykonanie
- Ustawienia proxy korporacyjnego
- Reguły firewall

Nie można zaimportować ustawień VS Code

Rozwiązanie: Upewnij się, że VS Code jest zamknięty podczas importu. Jeśli to nie pomaga:

Eksportuj ustawienia VS Code ręcznie: Code > Preferences > Profiles > Export
Importuj w Cursor: File > Preferences > Profiles > Import

Problemy z funkcjami AI

Automatyczne uzupełnianie Tab nie działa

Sprawdź limity planu

Poziom darmowy: 2,000 uzupełnień/miesiąc Poziom Pro: Nieograniczone Zobacz użycie w Ustawienia → Subskrypcja

Zweryfikuj indeksowanie

Ustawienia → Funkcje → Indeksowanie bazy kodu Powinien pokazywać status “Indeksowane” Kliknij “Reindeksuj” jeśli potrzeba

Status modelu

Sprawdź status.cursor.sh Model Tab może mieć problemy Spróbuj przełączyć na model zapasowy

Wsparcie plików

Niektóre typy plików mają ograniczone wsparcie Sprawdź czy Twój język jest wspierany Spróbuj w standardowym pliku .js/.py

Tryb agenta nie może modyfikować plików

Typowe przyczyny i rozwiązania:

Wybrany zły tryb
- Upewnij się, że wybrano “Agent”, nie “Chat”
- Tryb agenta pokazuje ikonę ołówka

Uprawnienia do plików

# Sprawdź uprawnienia pliku
ls -la nazwa_pliku
# Napraw jeśli potrzeba
chmod 644 nazwa_pliku

Blokady Git

# Usuń blokadę indeksu git
rm .git/index.lock

Pliki tylko do odczytu
- Sprawdź czy plik nie jest oznaczony jako tylko do odczytu
- Zweryfikuj, że masz dostęp do zapisu w katalogu

Zmniejsz pliki @-wspomniane
Użyj konkretnych zakresów linii: @plik.js:10-50
Wyczyść czat i zacznij od nowa

// Zamiast dołączać cały plik
@duzy-plik.ts

// Dołącz konkretne sekcje
@duzy-plik.ts:100-200  // Tylko istotną funkcję
@duzy-plik.ts:exported  // Tylko eksporty
@duzy-plik.ts:UserClass // Tylko konkretną klasę

Włącz tryb Max dla kontekstu 200k (kosztuje więcej):

Kliknij menu modelu → Włącz tryb Max

Otrzymywanie “Rate limit exceeded”

Twoje szybkie zapytania się wyczerpały. Opcje:

Czekaj na wolne zapytania (nieograniczone ale opóźnione)
Ulepsz plan dla większej liczby szybkich zapytań
Użyj swojego klucza API dla nieograniczonego (płać za użycie)
Sprawdź użycie: Ustawienia → Subskrypcja → Użycie

Problemy z wydajnością

Cursor działa wolno

Wyłącz nieużywane rozszerzenia
- Widok → Rozszerzenia
- Wyłącz nieistotne
Zmniejsz zakres indeksowania
.cursorignore
```
node_modules/
dist/
*.log
coverage/
```
Wyczyść cache
- Cmd/Ctrl + Shift + P → “Clear Editor History”
- Zrestartuj Cursor
Sprawdź zasoby systemowe
- Zamknij inne ciężkie aplikacje
- Upewnij się, że jest dostępny odpowiedni RAM

Wysokie użycie pamięci

Typowe w dużych bazach kodu. Rozwiązania:

Wyklucz duże katalogi z indeksowania
Używaj .cursorignore agresywnie
Rozważ podział przestrzeni roboczych monorepo
Zamknij nieużywane karty i okna edytora

Problemy z Claude Code

Problemy z instalacją

Command not found: claude

npm
Problemy z PATH

# Przeinstaluj globalnie
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Sprawdź instalację
npm list -g @anthropic-ai/claude-code

# Dodaj npm global do PATH
export PATH="$PATH:$(npm config get prefix)/bin"

# Uczyń stałym (dodaj do ~/.bashrc lub ~/.zshrc)
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc

Windows: błąd “Git not found”

Claude Code wymaga Git dla Windows:

Pobierz z git-scm.com
Zainstaluj z opcją “Add to PATH”
Zrestartuj terminal
Zweryfikuj: git --version

Problemy z uwierzytelnieniem

Klucz API nie działa

Zweryfikuj format klucza
- Powinien zaczynać się od sk-ant-
- Brak dodatkowych spacji lub cudzysłowów
Sprawdź uprawnienia klucza
- Zaloguj się do console.anthropic.com
- Zweryfikuj, że klucz jest aktywny
- Sprawdź limity użycia

Ustaw poprawnie

# Opcja 1: Zmienna środowiskowa
export CLAUDE_API_KEY="sk-ant-..."

# Opcja 2: Podczas konfiguracji
claude login

Przetestuj połączenie
Okno terminala
```
claude "hello"
```

Nieudane logowanie SSO

Dla enterprise SSO:

Upewnij się, że jesteś w sieci firmy/VPN
Sprawdź z IT reguły firewall
Spróbuj: claude login --sso --verbose
Użyj metody zapasowej klucza API jeśli potrzeba

Problemy z limitami użycia

”Rate limit reached” po kilku wiadomościach

Zrozumienie limitów:

Pro: ~45 wiadomości na 5-godzinne okno
Max 5x: ~225 wiadomości na 5-godzinne okno
Max 20x: ~900 wiadomości na 5-godzinne okno

Rozwiązania:

Optymalizuj użycie

# Czyść między zadaniami
/clear

# Grupuj powiązane pytania
claude "1. Napraw błąd X 2. Dodaj funkcję Y 3. Napisz testy"

Sprawdź pozostały limit
Okno terminala
```
/status
```
Użyj API dla intensywnych obciążeń
- Płać za token zamiast limitów wiadomości
- Brak ograniczeń czasowych

Problemy z wykonaniem

Błędy odmowy dostępu

Bezpieczne podejście
Tryb yolo

Skonfiguruj dozwolone komendy:

# Pozwól na konkretne komendy
claude config set allowed_commands "git,npm,ls"

# Pozwól na edycję plików
claude config set auto_approve_file_edits true

Pomiń wszystkie uprawnienia (używaj ostrożnie):

claude --dangerously-skip-permissions

Lub w kontenerze dla bezpieczeństwa:

docker run -it claude-safe claude --dangerously-skip-permissions

Zmiany nie są stosowane

Sprawdź katalog roboczy

pwd  # Upewnij się, że jesteś we właściwej lokalizacji

Zweryfikuj ścieżki plików
- Claude używa ścieżek względem katalogu roboczego
- Sprawdź literówki w nazwach plików

Status Git

git status  # Zobacz co się zmieniło
git diff    # Przejrzyj zmiany

Problemy z serwerami MCP

Problemy z połączeniem

Serwer MCP nie uruchamia się

Sprawdź instalację

npm list -g @modelcontextprotocol/nazwa-serwera

Zweryfikuj konfigurację

// ~/.claude/mcp.json lub .mcp.json
{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/github"]
    }
  }
}

Tryb debugowania
Okno terminala
```
claude --mcp-debug
```
Sprawdź logi
- Szukaj komunikatów błędów w wyjściu
- Typowe: brakujące zależności, problemy z uwierzytelnieniem

Błędy uwierzytelniania

GitHub MCP:

# Ustaw token PAT
export GITHUB_TOKEN="ghp_..."

Database MCP:

# Sprawdź string połączenia
export DATABASE_URL="postgresql://user:pass@localhost:5432/db"

Problemy z wydajnością

Operacje MCP przekraczają czas oczekiwania

Zwiększ timeout

{
  "servers": {
    "wolny-serwer": {
      "command": "...",
      "timeout": 30000  // 30 sekund
    }
  }
}

Sprawdź zasoby serwera
- Baza danych może być przeciążona
- Limity API
- Opóźnienia sieci

Typowe komunikaty błędów

Error: “Model is currently overloaded”

Znaczenie: Serwery modelów AI są na maksymalnej wydajności

Rozwiązania:

Poczekaj kilka minut i spróbuj ponownie
Przełącz się tymczasowo na inny model
Używaj w godzinach poza szczytem
Rozważ użycie API dla gwarantowanej dostępności

Error: “Invalid API key”

Sprawdź:

Klucz zaczyna się od prawidłowego prefiksu
Brak przypadkowych spacji/znaków
Klucz nie został odwołany
Używasz właściwego klucza dla właściwej usługi

Error: “Context length exceeded”

Rozwiązania:

Zmniejsz rozmiar wejścia
Użyj trybu Max (Cursor)
Podziel na wiele zapytań
Usuń niepotrzebny kontekst

Error: “File not found”

Typowe przyczyny:

Zły katalog roboczy
Literówka w nazwie pliku
Plik usunięty/przeniesiony
Wrażliwość na wielkość liter (Linux/Mac)

Procedury odzyskiwania

Uszkodzona historia czatu

Eksportuj obecny czat (jeśli możliwe)
- Cursor: Menu czatu → Eksportuj
- Claude Code: Skopiuj wyjście terminala
Wyczyść problematyczne dane
- Cursor: Usuń ~/.cursor/chats/
- Claude Code: Rozpocznij nową sesję
Przywróć z eksportu
- Wklej istotny kontekst z powrotem

Utracone zmiany w kodzie

Zapobieganie:

# Zawsze używaj git
git add -A && git commit -m "WIP: Przed zmianami AI"

Odzyskiwanie:

Sprawdź lokalną historię edytora
Szukaj plików .swp lub zapasowych
Użyj git reflog jeśli zakcommitowane
Sprawdź narzędzia odzyskiwania plików OS

Uzyskiwanie pomocy

Wbudowana diagnostyka

Cursor:

Pomoc → Toggle Developer Tools
Sprawdź konsolę dla błędów
Skopiuj i udostępnij wsparciu

Claude Code:

/doctor  # Uruchom diagnostykę
/help    # Pokaż dostępne komendy
claude --version  # Sprawdź wersję

Kanały wsparcia

Dokumentacja
- docs.cursor.com
- docs.anthropic.com
Społeczność
- Forum Cursor
- Discord
- Stack Overflow
Oficjalne wsparcie
- Enterprise: Priorytetowe wsparcie
- Pro: Wsparcie email
- Dołącz wyjście diagnostyki

Środki zapobiegawcze

Najlepsze praktyki unikania problemów

Regularne aktualizacje

# Cursor: Sprawdź aktualizacje w aplikacji
# Claude Code:
npm update -g @anthropic-ai/claude-code

Kopia zapasowa konfiguracji

# Kopia zapasowa ustawień Cursor
cp -r ~/.cursor ~/.cursor.backup

# Kopia zapasowa konfiguracji Claude Code
cp ~/.claude.json ~/.claude.json.backup

Monitoruj użycie
- Regularnie sprawdzaj limity
- Ustaw alerty użycia
- Śledź koszty użycia API
Używaj kontroli wersji
- Commituj przed głównymi operacjami AI
- Używaj gałęzi do eksperymentów
- Taguj stabilne wersje

Pamiętaj: Większość problemów ma proste rozwiązania. Zacznij od podstaw (restart, aktualizacja, sprawdź uprawnienia) przed próbowaniem złożonych napraw.