Typowe błędy wdrożenia i strategia ich debugowania

1. Anatomia wdrożenia: gdzie to w ogóle może się psuć

Warto najpierw zobaczyć cały łańcuch. Wdrożenie ChatGPT App w twojej architekturze można mentalnie rozwinąć w taką linię:

flowchart TD
  A[Twój laptop
git commit] --> B[Repozytorium Git
GitHub/GitLab]
  B --> C[Vercel Build
npm run build]
  C --> D[Vercel Deploy
Preview/Prod]
  D --> E[HTTP endpoint
/mcp, /api/...]
  E --> F[ChatGPT / Dev Mode
tool calls, widgets]

Błąd może pojawić się na każdym z tych kroków, ale objawy w ChatGPT wyglądają podobnie: "Error talking to app", "Network error" albo po prostu cisza. Twoim zadaniem jest nie strzelać na oślep, tylko najpierw zrozumieć: czy wywaliło się na etapie builda, podczas wykonywania, czy ChatGPT patrzy w złe miejsce.

Wygodnie dzielić problemy na trzy duże kategorie:

• Błędy builda: Vercel w ogóle nie zbudował projektu. Produkcja się nie zaktualizowała — to „dobrze”, ale widzisz czerwony build.
• Błędy runtime’u: build przeszedł, ale przy żądaniach pojawiają się 500/502, timeouty lub dziwne zachowanie.
• Config drift (dryf konfiguracji): lokalnie wszystko OK, na Vercel wszystko OK w logach, ale ChatGPT chodzi na stary URL, działa ze starym manifestem albo z pustymi zmiennymi env.

Przejdziemy przez te trzy warstwy i równolegle zbudujemy ogólną strategię debugowania.

2. Błędy builda: kiedy projekt się nie składa

To pierwszy typ problemów z wprowadzenia — błędy builda: projekt w ogóle się nie buduje, ponieważ Vercel nie potrafi poprawnie zbudować twojego projektu Next.js.

Node i Next.js: inne środowisko, inne wymagania

Lokalnie możesz (niestety) żyć ze starym Node, a Vercel spróbuje zbudować twój projekt Next.js 16 na wspieranej wersji Node (minimum 18.18.0). Jeśli w package.json jawnie wskazana jest niekompatybilna wersja, build może się wysypać w produkcji, choć dev‑serwer działał.

Prosty sposób, by się zabezpieczyć — w package.json jawnie podać "engines":

{
  "engines": {
    "node": ">=18.18.0"
  }
}

Wtedy zarówno lokalnie, jak i w CI/na Vercel wcześniej zobaczysz, że Node jest zbyt stary.

„U mnie działa!” i zapomniane zależności

Klasyka: zainstalowałeś bibliotekę przez npm install some-lib, ale nie zakomitowałeś zaktualizowanego package-lock.json albo w ogóle część zależności masz globalnie. Na Vercel aplikacja buduje się „od zera”, uczciwie wykonuje npm install na podstawie manifestu, a twojej ulubionej some-lib tam nie ma — mamy build error.

Pomaga twarda dyscyplina:

• każda nowa zależność jest dodawana i od razu commitowana;
• przed pushem na main/production uruchamiasz lokalnie npm run build. Jeśli lokalny build pada, na Vercel będzie tylko gorzej.

System plików rozróżniający wielkość liter

Lokalnie wiele osób siedzi na macOS albo Windows, gdzie system plików domyślnie nie rozróżnia wielkości liter w nazwie pliku. Na Vercel build idzie w środowisku Linux, tam Widget.tsx i widget.tsx to różne pliki.

Typowy błąd:

// Import w kodzie
import { AppWidget } from "@/components/Widget";

// A w repozytorium leży plik components/widget.tsx

Na twoim komputerze wszystko działa, na Vercel — błąd modułu „Cannot find module '@/components/Widget'”. Leczy się to porządkiem w nazwach i uważnym podejściem do wielkości liter.

Zmienne env na etapie builda

Kolejne źródło niespodzianek — używanie process.env.* w kodzie wykonywanym na etapie builda (np. w next.config.mjs albo modułach importowanych podczas builda). Jeśli lokalnie wczytałeś .env.local, a na Vercel zapomniałeś dodać te zmienne dla środowiska build, build albo upadnie, albo — co gorsze — przejdzie z undefined i „wypiecze” nieprawidłowe wartości w bundlu.

Dla ChatGPT App to szczególnie krytyczne, jeśli np. tworzysz baseURL dla endpointu MCP lub URL zewnętrznych API już na etapie builda.

Dobra praktyka — jawnie walidować krytyczne zmienne env jeszcze przed startem aplikacji (o czym za chwilę), żeby build padał głośno i przewidywalnie.

3. Błędy runtime’u: wszystko się zbudowało, ale nie działa

Przechodzimy do drugiej warstwy z wprowadzenia — błędów runtime’u: build przeszedł, ale podczas wykonania wszystko się sypie.

Build przeszedł, Vercel radośnie pokazał zielone wdrożenie, przełączyłeś ChatGPT App na prod‑URL — i w czacie zobaczyłeś "Error talking to app". To znaczy, że problemy przeszły na poziom wykonania.

Puste lub brakujące zmienne env

Najczęściej incydent produkcyjny w świecie ChatGPT App zaczyna się od słowa undefined. Lokalnie masz zadbany .env.local z OPENAI_API_KEY, MCP_BASE_URL i innymi, a na Vercel zapomniałeś dodać te zmienne albo pomyliłeś nazwy.

Na przykład czytasz:

const apiKey = process.env.OPENAI_API_KEY;

a na Vercel dodałeś OPENAI_APIKEY lub OPENAI_API_KEY_PROD. W rezultacie przy pierwszym wywołaniu narzędzia MCP twój route‑handler spada z błędem uwierzytelniania.

Znacznie lepiej, gdy aplikacja wywraca się od razu i jasno. Dobry wzorzec — osobny moduł w twoim projekcie Next.js, który waliduje zmienne env przy imporcie:

// app/lib/env.ts
const required = ["OPENAI_API_KEY", "MCP_BASE_URL"] as const;

type RequiredKey = (typeof required)[number];

function getEnv(key: RequiredKey): string {
  const value = process.env[key];
  if (!value) {
    throw new Error(`Missing required env var: ${key}`);
  }
  return value;
}

export const env = {
  OPENAI_API_KEY: getEnv("OPENAI_API_KEY"),
  MCP_BASE_URL: getEnv("MCP_BASE_URL"),
};

Teraz, jeśli zapomnisz ustawić zmienne na Vercel, Next.js wywali się przy pierwszym imporcie env, a w logach będzie czytelny komunikat "Missing required env var: ...".

Ważne: na Vercel zmiany zmiennych env nie są podbierane automatycznie. Po zmianie wartości trzeba zrobić nowy deploy (redeploy), inaczej runtime będzie dalej żył starymi wartościami.

Błędy w route‑handlerach i endpointzie MCP

W oficjalnym szablonie ChatGPT App serwer MCP jest zwykle zaimplementowany jako app/mcp/route.ts. W środku masz kod, który parsuje żądanie JSON‑RPC, routuje je do narzędzia i zwraca odpowiedź. Jeśli gdzieś w łańcuchu poleci throw bez obsługi — użytkownik w ChatGPT dostanie 500.

Warto zawsze opakować naj‑wyższy poziom MCP‑handlera w try/catch, zalogować błąd i zwrócić ustrukturyzowaną odpowiedź:

// app/mcp/route.ts
import { NextRequest, NextResponse } from "next/server";

export const dynamic = "force-dynamic";
export const maxDuration = 30; // sekundy

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    // tutaj obsługa żądania MCP
    const result = await handleMcpRequest(body);
    return NextResponse.json(result);
  } catch (error) {
    console.error("MCP route error", error);
    return NextResponse.json(
      { error: "Internal MCP error" },
      { status: 500 }
    );
  }
}

Kilka uwag:

• dynamic = "force-dynamic" pomaga uniknąć nieoczekiwanego statycznego generowania i cache’owania dla tras MCP w Next.js 16.
• maxDuration = 30 wyraźnie mówi Vercel, że route‑handler może działać do 30 sekund, co jest ważne przy długich żądaniach do LLM.

Timeouty i „Network error” w ChatGPT

Vercel ogranicza czas działania funkcji serverless: na darmowych planach to zwykle ok. 10 sekund, na płatnych może być więcej (do kilku minut). Jeśli twoje narzędzie MCP wykonuje długie żądanie do bazy lub zewnętrznego API, może nie zdążyć odpowiedzieć, a ChatGPT otrzyma "Network error" albo przerwany strumień.

Jeśli używasz streamingu (SSE) dla częściowych wyników, szczególnie ważne jest wysłać pierwsze bajty odpowiedzi przed upływem limitu. Wtedy sama transmisja może trwać dłużej, ale platforma nie uzna funkcji za „zawieszoną”.

Mała sztuczka: mierz czas wywołań narzędzi i loguj go razem z nazwą narzędzia. W logach zobaczysz, że np. search_flights stabilnie zajmuje 12 sekund i minimalnie nie mieści się w limicie.

export async function safeToolCall<TInput, TOutput>(
  name: string,
  handler: (input: TInput) => Promise<TOutput>,
  input: TInput
): Promise<TOutput> {
  const started = Date.now();
  try {
    const result = await handler(input);
    console.log("[tool] ok", name, { ms: Date.now() - started });
    return result;
  } catch (error) {
    console.error("[tool] fail", name, {
      ms: Date.now() - started,
      error,
    });
    throw error;
  }
}

Potem zamiast handler(args) wywołujesz safeToolCall("search_flights", handler, args).

Sieć i usługi zewnętrzne

Czasem chodzi o banalne https:// zamiast http:// albo przestarzały baseURL. Zwłaszcza gdy najpierw testowałeś na maszynie lokalnej z jednym URL‑em, a na produkcji masz już inną domenę lub inny port.

Warto wynieść bazowe URL‑e do konfiguracji (zależnej od środowiska) i nie wszywać ich bezpośrednio w kod narzędzia. Wtedy przy zmianie środowiska zmieniasz jedną zmienną env, zamiast pamiętać, w których pięciu miejscach w kodzie miałeś http://localhost:3001.

4. Konfiguracja i dryf środowisk

I wreszcie trzeci typ z naszej schemy — dryf konfiguracyjny między środowiskami.

Nawet jeśli build przeszedł i runtime według logów jest zdrowy, ChatGPT może zachowywać się „jakby działała nie ta wersja aplikacji”. To właśnie przypadek, gdy problem leży nie tyle w kodzie, co w konfiguracji i spójności środowisk.

Dev Mode kontra produkcja

W Dev Mode ChatGPT patrzy na Connector URL, który podałeś ręcznie: zwykle to URL tunelowy (https://myapp-dev.ngrok-free.app/mcp lub coś podobnego) albo staging‑URL na Vercel. W produkcji (przez Store lub ustawienia organizacji) App powinien wskazywać stabilny endpoint produkcyjny, np. https://myapp.vercel.app/mcp.

Błąd, który popełnia prawie każdy: wdrożyłeś na Vercel, ale w ustawieniach ChatGPT App nadal widnieje stary tunelowy URL. Serwer lokalny jest wyłączony, tunel dawno padł, a ChatGPT grzecznie puka tam i dostaje 502. W interfejsie wygląda to jak "Error talking to app", i student zaczyna naprawiać kod MCP, który w ogóle się nie wykonuje.

Leczy się to dyscypliną: po każdej zmianie środowiska (tunel → staging, staging → prod) sprawdzasz, jaki dokładnie URL jest wpisany w Dev Mode i w konfiguracji produkcyjnej App.

Stary manifest i cache ChatGPT

ChatGPT będzie cache’ował informacje o twojej aplikacji: listę narzędzi, ich opisy, metadane. Dlatego sytuacja „zmieniłem schemat narzędzia, a model wciąż uważa, że argument nazywa się po staremu” — jest jak najbardziej realna.

Przy poważnych zmianach narzędzi warto:

• upewnić się, że naprawdę wdrożyłeś nową wersję (zobaczyć commit hash w logach, wyświetlić go w logu startowym);
• odtworzyć lub ponownie podłączyć App w Dev Mode, aby wymusić odczyt manifestu przez platformę;
• na czas debugowania pracować przez MCP Inspector, gdzie na pewno widać aktualną listę narzędzi i schematy.

Konfiguracja env: dev/staging/prod

Już mówiliśmy, jak zmienne env mogą położyć build i runtime. Tutaj — spojrzenie z góry na dev/staging/prod i spójność wartości między nimi.

Częsty ból: .env.local masz idealny, a w środowiskach Vercel — zoo. W efekcie:

• lokalnie masz jeden klucz API i jeden URL zewnętrznej usługi;
• na stagingu — zupełnie inne wartości;
• na produkcji — połowa zmiennych nie jest ustawiona.

Bardzo pomaga prosty plik tekstowy docs/env.md w repozytorium, w którym wylistujesz: jakie zmienne są potrzebne, w których środowiskach są obowiązkowe, jakie są przykładowe wartości. Może to wyglądać na biurokrację, ale w momencie incydentu taka lista oszczędza godziny.

5. Jak wyglądają błędy po stronie ChatGPT

Spójrzmy na sytuację oczami użytkownika ChatGPT. On widzi tylko interfejs i nie wie nic o Vercel, Node i MCP. A ty, niestety, też jeszcze nie wiesz, co dokładnie się zepsuło.

Typowe symptomy w ChatGPT:

• komunikat "Error talking to [App Name]" zaraz po próbie użycia;
• nieskończony spinner bez widocznego błędu;
• czerwony tekst "I encountered an error while running the tool";
• widget się nie pojawia albo pojawia się pusty.

Każdy z tych symptomów zwykle odpowiada określonemu poziomowi usterki:

• jeśli App jest w ogóle niedostępny (zły URL, tunel padł, błąd SSL), ChatGPT nie może dostać się do twojego endpointu MCP — sprawdź dostępność domeny w przeglądarce i logi Vercel z kodami 4xx/5xx;
• jeśli MCP odpowiada poprawnym JSON‑RPC z polem error, ChatGPT uczciwie pisze, że narzędzie zwróciło błąd — to już kwestia logiki biznesowej lub walidacji argumentów;
• jeśli MCP odpowiada sukcesem, ale w odpowiedzi jest uszkodzony HTML widgetu lub błąd JS, to w konsoli widgetu (DevTools → iframe widgetu) będzie widać, co dokładnie padło.

Dlatego dobra praktyka: gdy tylko zobaczysz dziwne zachowanie w czacie, od razu zapisz timestamp (dokładność do minuty) i idź do logów Vercel szukać żądań z tego czasu.

6. Strategia debugowania: nie panikować, tylko działać

Złóżmy teraz z tego wszystkiego krótki „playbook” — scenariusz działania, gdy coś poszło nie tak. Cel — zastąpić bieganie w kółko spokojnym algorytmem.

Krok 1: określamy typ problemu

Jeśli build na Vercel jest czerwony — cieszymy się: błąd złapany przed produkcją. Otwieramy logi builda, patrzymy na pierwszy rzeczywisty błąd (a nie 200 linii ostrzeżeń) i odtwarzamy lokalnie komendą npm run build.

Jeśli build jest zielony, a ChatGPT narzeka — to runtime lub konfiguracja. Sprawdzamy:

• czy prod‑URL twojej aplikacji jest dostępny z przeglądarki (https://myapp.vercel.app/mcp zwraca cokolwiek);
• czy endpoint MCP zwraca 200/500, czy w ogóle się nie rozwiązuje;
• czy URL w ustawieniach App pokrywa się z tym, który właśnie sprawdziłeś.

Krok 2: czytamy logi, a nie myśli

Kolejny przystanek — logi Vercel: logi serwerowe dla właściwego wdrożenia i właściwego środowiska (Preview/Production).

Szukamy:

• błędów Error: Missing required env var ... — to znaczy, że problem jest w konfiguracji;
• stack trace z MCP‑handlera — czyli pada logika biznesowa albo parsowanie danych wejściowych;
• komunikatów o timeoutach lub przekroczeniu czasu działania funkcji.

Równolegle pamiętamy o MCP Inspector. Jeśli podłączysz się do tego samego endpointu MCP przez inspektor i ręcznie wywołasz narzędzia, szybko stanie się jasne, czy problem jest w samym MCP, czy w parze ChatGPT ↔ MCP.

Krok 3: szybki rollback czy hotfix?

Jeśli widzisz, że wdrożenie produkcyjne jest wyraźnie zepsute (np. trasa MCP stale rzuca ten sam błąd przy każdym żądaniu), a poprzednie wdrożenie było zdrowe, właściwą decyzją jest się cofnąć. Vercel pozwala szybko przełączyć się na wcześniejsze udane wdrożenie bez przebudowy — to w zasadzie zmiana aktywnej wersji.

To lepsze niż próba naprawiania produkcji „w locie”, zwłaszcza jeśli nie do końca rozumiesz przyczynę incydentu.

Gdy sytuacja jest ustabilizowana, spokojnie analizujesz przyczynę, dopisujesz testy, naprawiasz w kodzie i dopiero potem wypuszczasz kolejną wersję.

Krok 4: utrwalamy wiedzę w dokumentacji

Każdy poważny incydent to pretekst, by zaktualizować wewnętrzny README:

• dodać do listy obowiązkową zmienną env, bez której wszystko pada;
• zanotować, jaki dokładnie przypadek doprowadził do błędu (np. „import z niewłaściwą wielkością liter w nazwach plików”);
• opisać krótki algorytm działań, który pomógł szybko wszystko naprawić.

To może wydawać się nudne, ale za kilka miesięcy sam sobie podziękujesz.

7. Kilka praktycznych trików w kodzie

Weźmy kilka kroków z naszego playbooka i wzmocnijmy je małymi trikami w kodzie w naszej aplikacji szkoleniowej (ChatGPT App).

Jednolity moduł konfiguracji

Pisaliśmy już prosty walidator zmiennych env. Można go rozbudować, aby rozróżniał środowiska:

// app/lib/config.ts
type NodeEnv = "development" | "test" | "production";

const nodeEnv = (process.env.NODE_ENV || "development") as NodeEnv;

const requiredBase = ["OPENAI_API_KEY"] as const;
const requiredProd = ["MCP_BASE_URL"] as const;

function ensure(keys: readonly string[]) {
  for (const key of keys) {
    if (!process.env[key]) {
      throw new Error(`Missing env var ${key} for NODE_ENV=${nodeEnv}`);
    }
  }
}

ensure(requiredBase);
if (nodeEnv === "production") {
  ensure(requiredProd);
}

export const config = {
  nodeEnv,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  mcpBaseUrl: process.env.MCP_BASE_URL ?? "http://localhost:3000/mcp",
};

Taki moduł od razu podświetli, jeśli produkcja wystartuje bez potrzebnej zmiennej.

Logowanie przychodzących żądań MCP

Prosta, ale bardzo użyteczna otoczka dla MCP‑handlera:

// app/lib/mcp-logger.ts
export function logMcpRequest(body: unknown) {
  console.log("[mcp] request", {
    time: new Date().toISOString(),
    // nie logujemy danych wrażliwych
    keys: typeof body === "object" && body !== null
      ? Object.keys(body as Record<string, unknown>)
      : typeof body,
  });
}

I używamy w app/mcp/route.ts:

import { logMcpRequest } from "@/app/lib/mcp-logger";

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    logMcpRequest(body);
    const result = await handleMcpRequest(body);
    return NextResponse.json(result);
  } catch (error) {
    console.error("MCP route error", error);
    return NextResponse.json({ error: "Internal error" }, { status: 500 });
  }
}

W logach będziesz widzieć, co w ogóle przychodzi od ChatGPT: choćby po kluczach ("jsonrpc", "method", "params"), i łatwiej zrozumiesz, które wywołanie pada.

Prosty healthcheck endpointu MCP

Czasem warto mieć niewielki route‑handler w rodzaju „healthcheck” dla serwera MCP, którego ChatGPT bezpośrednio nie woła, ale możesz szybko otworzyć go w przeglądarce i sprawdzić, czy serwer żyje i widzi swoje zmienne env:

// app/api/health/route.ts
import { NextResponse } from "next/server";
import { config } from "@/app/lib/config";

export async function GET() {
  return NextResponse.json({
    status: "ok",
    env: config.nodeEnv,
    hasOpenAiKey: !!config.openaiApiKey,
  });
}

Jeśli https://myapp.vercel.app/api/health odpowiada status: "ok", to znaczy, że przynajmniej podstawowy pipeline do twojego kodu Node żyje.

8. Typowe błędy przy wdrożeniu i debugowaniu

Błąd nr 1: Wdrożenie bez lokalnego npm run build.
Gdy programista nigdy nie uruchamia builda lokalnie, dowiaduje się o niekompatybilnej wersji Node, problemie ze ścieżkami lub błędzie TS dopiero na Vercel. To wydłuża cykl „zepsułem → naprawiłem”, bo każdy eksperyment to nowy deploy. Nawyk odpalania npm run build przed pushem na main oszczędza mnóstwo czasu (zob. też rozdział 2 i krok 6.1 o lokalnym npm run build).

Błąd nr 2: Sekrety zostały tylko w .env.local.
Projekt pięknie działa na maszynie autora, ale w produkcji pada, bo process.env.OPENAI_API_KEY === undefined. Powód banalny: zmienne env zapomniano dodać w ustawieniach Vercel (a czasem nawet nazwano je inaczej). Szczególnie często zapomina się o rozdzieleniu Development/Preview/Production i dziwi, że staging i prod zachowują się inaczej (więcej — rozdziały 3.1, 4.3 i 7.1).

Błąd nr 3: Użycie NEXT_PUBLIC_* dla sekretów.
W Next.js wszystkie zmienne z prefiksem NEXT_PUBLIC_ trafiają do bundla przeglądarkowego. Jeśli przez nieuwagę nazwałeś klucz API NEXT_PUBLIC_OPENAI_API_KEY, wyjedzie do przeglądarki użytkownika i może zostać wyciągnięty z devtoolsów. Tak nie wolno. Publiczne powinny być tylko bezpieczne wartości (np. identyfikatory feature flagów, ale nie tokeny).

Błąd nr 4: Ignorowanie logów Vercel i próba „naprawiania przez ChatGPT”.
Czasem programista widzi w czacie "Error talking to app" i godzinami zmienia prompt, opisy narzędzi, coś dłubie w Dev Mode, ale ani razu nie zagląda do logów serverless. A tam stoi całkiem zrozumiały błąd: "Missing env var", "Cannot find module" albo stack trace konkretnego narzędzia. Dobry inżynier najpierw patrzy w logi, a dopiero potem dyskutuje z modelem.

Błąd nr 5: Pomylenie Dev Mode i aplikacji produkcyjnej.
Po pierwszym udanym wdrożeniu na Vercel łatwo zapomnieć, że Dev Mode wciąż może patrzeć na stary tunel albo na preview‑URL. W rezultacie jesteś pewien, że testujesz wersję produkcyjną, a tak naprawdę rozmawiasz z lokalną gałęzią, którą dawno trzeba było usunąć. Albo odwrotnie: myślisz, że testujesz robocze zmiany, a ChatGPT puka w bojowy endpoint. Trzeba regularnie sprawdzać, jaki URL jest podany w ustawieniach App i Dev Mode (zob. też rozdział 4.1 o Dev Mode i produkcji).

Błąd nr 6: Oczekiwanie, że zmiana zmiennej env na Vercel zadziała „na żywo”.
Niektórzy zmieniają wartości zmiennych w panelu Vercel i od razu biegną do ChatGPT sprawdzać wynik. Ale runtime wciąż używa starych wartości, bo nie było redeploy. Każda zmiana zmiennych env wymaga nowego wdrożenia, inaczej funkcja nie zobaczy aktualizacji (więcej — rozdział 3.1).

Błąd nr 7: Brak prostej strategii rollback.
W momencie incydentu kusi, by „szybko wypchnąć fixa” prosto na main. Ale to dokłada kolejne potencjalnie zepsute wdrożenie, a użytkownicy cały czas cierpią. Znacznie spokojniej mieć nawyk: przy poważnym błędzie od razu cofnąć się do poprzedniego udanego wdrożenia, naprawić problem w osobnej gałęzi i dopiero potem wydać nową wersję. Vercel daje do tego wygodny interfejs — grzech nie korzystać.