freemius-troubleshooting

Freemius のトラブルシューティング

Freemius の連携で問題が発生した場合、原因はほとんどの場合、次の5つのいずれかです：ウェブフック／リダイレクトの設定、SDK の型／イベント、スタック／移植レイヤー、チェックアウト／ポータルの接続、またはシークレット／ダッシュボードの設定。この Skill は診断用のインデックスです。症状を見つけ、該当するリファレンスを開いて修正を適用してください。

FAQ の原文： https://freemius.com/help/documentation/ai/lovable/#troubleshooting

この Skill の使い方

1. 以下の表で該当する症状を確認します。
2. リンク先のリファレンスを開き、根本原因と修正方法を確認します。
3. freemius-core／freemius-checkout／freemius-customer-portal に関する問題の場合、リファレンスから該当する Skill の正確なセクションに移動できます。

症状 → 修正方法のインデックス

症状	考えられる原因	参照
チェックアウトは完了するが、ユーザーがアクセス権を取得できない	リダイレクト URL または Webhook が設定されていない／公開されていない	references/webhooks-and-redirect.md
Webhook の署名検証に失敗する	リスナーに渡す前に、Raw body がパースされている	references/webhooks-and-redirect.md
Entitlement の type に対する TS エラー：Type '"lifetime"' is not assignable	Entitlement の type は subscription | oneoff であり、lifetime ではありません	references/sdk-types-and-events.md
license.quota.changed を購読しても何も起きない／型エラーになる	@freemius/[email protected] にそのイベントは存在しません	references/sdk-types-and-events.md
Webhook ハンドラー内の license に対する TS エラー：Object is possibly 'false'	配列サブスクリプションの license は、削除済みの形式を含むユニオン型です	references/sdk-types-and-events.md
prisma generate／クライアントでドライバーアダプターを要求される；url が拒否される	Prisma 7 では従来の datasource url が削除されています。Prisma 6 に固定してください	references/stack-and-porting.md
ブラウザーで process.env.NEXT_PUBLIC_* が undefined になる	Vite では process.env ではなく、import.meta.env.VITE_* を使用します	references/stack-and-porting.md
@/... または @shared/... のインポートを解決できない	vite.config.ts と tsconfig の paths にエイリアスがありません	references/stack-and-porting.md
npx skills add でスキルをインストールしたが、Claude Code（CLI）に表示されない／スラッシュコマンドが見つからない	Claude Code はデフォルトのインストール先ではありません。スキルは ~/.agents/skills/ にインストールされ、~/.claude/skills/ へのシンボリックリンクがありません	references/stack-and-porting.md
Claude Desktop（Claude.ai アプリ）で npx skills add … -a claude-code の CLI 方式を試したが、適用されない	CLI／-a claude-code フラグは Claude Code 専用の概念です。Desktop では、Customize → Skills → "+" → Upload a skill から各スキルの .zip を個別にインストールします（最初に core をインストールし、Settings → Capabilities で Code execution を有効にしてください）	references/stack-and-porting.md
シークレットキー／API トークンがブラウザーに漏れる、または Freemius から 401 が返る	Freemius の呼び出しがサーバー側ではなくクライアント側で行われています	references/checkout-and-portal.md
チェックアウトオーバーレイが空または未設定の状態で開く	サーバーで作成した CheckoutSerialized からオーバーレイが初期化されていません	references/checkout-and-portal.md
アップグレードのルートが 500 を返す：「Payment method update is not allowed for lifetime licenses」	checkout.create({ licenseId }) は、更新可能なライセンス（expiration: null）を拒否する支払い方法更新エンドポイントを呼び出します。setLicenseUpgradeByKey を使用してください	references/checkout-and-portal.md
ユーザーが「アップグレード」したが、サブスクリプションが 2 つになった／二重請求された	すでにサブスクリプションに加入しているユーザーに、通常のサブスクライブ用チェックアウトを提示しています。ライセンスアップグレード用チェックアウト（setLicenseUpgradeByKey）と、entitlement を考慮した表示を使用してください	references/checkout-and-portal.md
ポータルの操作で 404 が返る／トークンが無効	/api/portal エンドポイント 1 つで、データと署名付きアクションの両方を処理する必要があります	references/checkout-and-portal.md
1 回限り／Lifetime の購入がサブスクリプションのデモと同じように動作しない	課金方式が異なります。billing_cycle: 'lifetime' と type oneoff を使用してください	references/checkout-and-portal.md
Lifetime にアップグレードしたのに、引き続き機能が制限される／クレジットが請求される／アクティブとして表示されない（請求書は正しい）	freemius.entitlement.getActive() は type: 'subscription' で絞り込むため、1 回限りの Lifetime 行は表示されず、getUserEntitlement() は null を返します	references/sdk-types-and-events.md
クーポン適用済みのサブスクリプションが約 100 年後に「更新」される（USD 0 · renews 2126）	100％オフのクーポンが「初回の支払いと更新」に適用されています	references/checkout-and-portal.md
キャンセル後の再サブスクライブが拒否される（「すでにアクティブなサブスクリプションに加入しています」）	管理者がライセンスをキャンセルしたため、サブスクリプションが孤立したままアクティブになっています	references/checkout-and-portal.md
アクティブなサブスクリプションに加入しているのに、ユーザーにペイウォール／402 が表示される；user_fs_entitlement テーブルが空	オーバーレイの purchaseCompleted 同期と Dashboard のチェックアウトリダイレクト URL を設定せずに、ホスト型のリダイレクトだけを使ってチェックアウトしました。そのため、entitlement の行が書き込まれていません	references/checkout-and-portal.md
すべてのユーザーで user_fs_entitlement が空；同期 POST が 400 "License ID is required in the request body" を返す（フロントエンドの .catch() がエラーを隠す）	オーバーレイの purchaseCompleted POST が checkout.request.createProcessor／processRedirect 経由でルーティングされている（または syncEndpoint が /api/checkout/redirect?action=process_purchase を指している）ためです。この経路は、オーバーレイのペイロードにない署名付きリダイレクト／本文中の license_idを要求します。オーバーレイの同期には、ペイロードからライセンスを読み取り syncEntitlementByLicenseId を呼び出す通常の POST /api/purchase を使用してください。これはホスト型の GET /api/checkout/redirect とは別のエンドポイントです	freemius-checkout → references/checkout-provider.md
制限付き機能（例：Premium の画像 OCR）で、一般的な 「OCR failed. Please try another file.」 と表示される	サーバーのティア／entitlement ゲート（tier_upgrade_required／image_requires_pro などの理由を伴う 403／402）が、すべてのエラーを処理する catch によって握りつぶされています。ゲートは失敗ではありません。ステータスと理由に応じて分岐し、エラートーストではなく、アップグレード経路を提示するペイウォールを開いてください	freemius-checkout → references/paywall.md
購入は成功するが、料金ページがない／最初にペイウォールに到達しなくても、プランを確認したり購入したりする方法がない	ビルドにペイウォールは含まれていますが、独立した料金ページのルートが抜けています。専用の /pricing ページ（GET /api/checkout/pricing から取得する Subscribe + Topup テーブル）とナビゲーションリンクは、必須の成果物です	freemius-checkout → references/pricing-tables.md
サブスクリプションの購入後（または Lifetime に不適切な文言で）、成功トーストに 「credits added to your account」 と表示される	購入後の文言が、同期された購入タイプに応じて分岐していません。再取得した entitlement のティアを使ってください。lifetime →「Lifetime access unlocked」、subscription →「<tier> unlocked」、クレジットパック →「page credits added」	freemius-checkout → references/checkout-provider.md
OCR（従量制）の実行後、手動でページを更新するまでクレジット残高に古い値が表示される	サーバーはクレジットを正しく差し引いています（credit -= pages）が、従量制アクションの成功ハンドラーが表示中の残高を更新しないため、完全に再読み込みするまでバッジが古いままです。再読み込みせずに表示を更新するには、アクションのレスポンスから新しい残高を読み取るか、購入フローと同じ refreshEntitlement()（GET /api/entitlement → credit）を await してください。これは、購入後の entitlement 更新に対応する、利用後の更新です	freemius-checkout → references/paywall.md
Lifetime／最上位ティアのユーザーで /pricing に何も表示されない（「何も表示されなくなった」）	購入対象の最上位ティアをすでに所有しているため、すべての購入画面が正しく非表示になっていますが、すべてを隠すと空白のページが残ります。代わりに「すべて所有しています」という親切な空状態を表示してください。空白のページにしてはいけません（クレジットのみの利用者には、Subscribe + Topup を引き続き表示する必要があります）	freemius-checkout → references/pricing-tables.md
アカウントページの 「Change plan」 が、キャンセルの隣で位置がずれた、パディングのない下線付きリンクとして表示される	ボタン用のクラス（例：btn-outline）が指定されたルーターの <Link> ですが、そのクラスは基本の .btn クラスからパディング、角丸、text-decoration:none のみを継承します。<a> に単独で適用すると、そのすべてが失われます。ボタン／アウトラインのクラスを単独で完結するようにするか、基本クラスと修飾クラスの両方を <Link> に設定してください	freemius-customer-portal → references/subscription-and-upgrade.md
継続利用クーポン：「割引を適用してプランを継続」をクリックするとウィザードが閉じるだけで、何も起きず、Dashboard の 利用回数が 0 と表示される	適用 POST の本文が空の {} でした。SDK の更新クーポンアクションは { couponId: <coupons[0].coupon_id> } を要求し、それ以外の場合は 400 を返します。また、ウィザードが res.ok を確認していないため、呼び出しに失敗しても成功したかのように閉じます。実際の couponId を送信し、res.ok を確認してください（失敗時はエラーを表示し、ウィザードを開いたままにします）	freemius-customer-portal → references/cancellation-and-coupon.md
ホスト型チェックアウト／アップグレード後、ブラウザーが /checkout-result?success=true に移動し、ヘッダーだけの空白ページが表示される	サーバーの GET リダイレクトハンドラーは /checkout-result に移動させますが、SPA ルーター（App.tsx の <Routes>）には一致するクライアントルートがありません。ビルドで出し忘れた実ページがリダイレクト先になっています。success を読み取り、マウント時に entitlement を 1 回更新し、確認メッセージを表示してアプリに戻る /checkout-result ルートを追加してください	freemius-core → references/purchase-processing.md
キャンセル／更新後に entitlement が更新されない。Webhook が機能していないように見えるが、ハンドラー、URL、署名に問題はない	Dashboard で Webhook URL が有効化／反映される前にライフサイクルイベントが発生したため、配信されていません（後から再送もされません）	references/webhooks-and-redirect.md

最初に確認する項目（Lovable FAQ の基本）

このスタックに適用した、公式 FAQ の最優先の推奨事項です。

1. 失敗した手順を再実行するようエージェントに依頼してください。 これらのスキルはモジュール式です。全体をやり直すのではなく、該当するリファレンス（例：freemius-core → purchase-processing.md）を再度呼び出してください。
2. Webhook とチェックアウト後のリダイレクトが、重要な 2 つの経路です。 まず両方をエンドツーエンドで確認してください。「支払い後にアクセスできない」という報告の多くは、どちらかの設定ミスが原因です。Webhook の処理に失敗すると Freemius からメールが届くため、そのメールの内容をエージェントに貼り付けると、失敗箇所を特定できます。
3. 公開／デプロイ後は、すべての URL を更新してください。 リダイレクト URL または Webhook URL がまだ localhost（または古いドメイン）を指していると、フローが気付かないうちに機能しなくなります。PUBLIC_APP_URL は公開中のドメインに設定する必要があります。
4. 買い切り購入には、サブスクリプションの場合とは異なる方法が必要です。lifetime モダリティについては、チェックアウト／ポータルのリファレンスを参照してください。
5. それでも解決しない場合は、 Freemius サポート（[email protected]）に、プロダクト ID、失敗した手順、スクリーンショットを添えてお問い合わせください。

新しい項目の追加

このスキルは拡張していくことを想定しています。検証ゲート中にスキルの不具合が見つかった場合は、そのゲートの「見つかったスキルの不具合」テーブルに記録し、該当するスキルを修正したうえで、ここにトラブルシューティングの項目（症状 → 原因 → 解決方法）を追加してください。そうすれば、次のインテグレーターが同じ問題につまずかずに済みます。