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

Fabric Apps プロジェクトを開発またはデプロイするときの一般的な問題を診断します。この記事では、サインイン、ローカルサービス、スキーマの変更、静的ホスティング、CLI に関する問題について説明します。

デプロイメントの問題

401 または 403 エラーでデプロイが失敗する

症状：npx rayfin upを実行すると、認証エラーが返されます。

原因： 認証セッションの有効期限が切れているか、サインインしていません。

Solution:

再認証し、デプロイを再試行します。

npx rayfin login
npx rayfin up

静的デプロイがサイズ制限を超えています

症状： 静的コンテンツのデプロイは、サイズ制限エラーで失敗します。

原因： 圧縮アーカイブが 100 MB を超えています。

Solution:

次の方法でビルド出力サイズを小さくします。

運用ビルドからのソースマップの除外
大きな画像やビデオを最適化または削除する
バイナリファイルをバンドルするのではなく、ストレージに移動する
バンドラ構成で開発用成果物が除外されることを確認する

静的デプロイメントにはリモートエンドポイントはありません

症状:npx rayfin up staticapp deploy実行するとリモートエンドポイントの設定がされていないと報告されます。

原因: 静的のみ展開は既存の展開を更新します。最初のリモートアプリをプロビジョニングできません。

Solution:

フルデプロイメントを一度実行する:

npx rayfin up

プロビジョニング完了後は、 npx rayfin up staticapp deploy を使って以降の静的のみ更新を行います。

認証の問題

認証トークン取得の失敗

症状:npx rayfin login または別の認証済みCLIコマンドが Failed to acquire authentication token や認証情報保存エラーを報告します。

原因: CLIがサインインしていないか、環境がオペレーティングシステムバックアップの認証情報ストレージを提供していない。

Solution:

再度サインイン:

npx rayfin login

認証情報ストレージのない制限されたローカル開発環境では、暗号化のフォールバックを有効にすることができます:

npx rayfin login --encryption-fallback-enabled

Warning

暗号化フォールバックはトークンキャッシュを平文で保存します。信頼できる開発環境でのみ使用してください。本番環境や共有環境では使わないでください。

症状： ユーザーは認証の直後にサインアウトされます。

原因： クライアントが正しいベース URL または発行可能なキーで構成されていません。

Solution:

RayfinClient構成がバックエンドと一致するかどうかを確認します。

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Symptom: ブラウザーは、サインイン時にFabricポータルウィンドウをブロックします。

原因:ensureSignedInWithFabric() は、ユーザージェスチャハンドラーから呼び出されませんでした。

Solution:

同期イベントハンドラーから関数を呼び出します。

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Fabric認証はタイムアウトします

症状:Fabric認証が5分後に失敗します。

原因:Fabricポータルはフローが終了する前にハンドオフコードを返しませんでした。

Solution:

returnOriginがアプリの発信元と一致しているか確認し、ポップアップを閉じてサインインの流れを再開してください。

Fabric SSOが発信元不一致を報告します

症状:FabricのSSOハンドオフは、発信元が一致しないため応答を拒否します。

Cause:returnOrigin、allowedRedirectUris、またはfabricPortalUrlは、アプリやFabricポータルが動いている環境と一致しません。

Solution:

returnOrigin をアプリのベアオリジンに設定してください。
起源が services.auth.allowedRedirectUrisに現れていることを確認してください。
正しい本番環境、プレビュー環境、開発環境はFabricポータルのURLを使用してください。
npx rayfin upを変更した後、rayfin.ymlを実行してください。

詳細は「認証リダイレクトURIの設定」をご覧ください。

`initEmbeddedAuth()` は `null` を返します。

症状: 埋め込み認証はセッションを作成しません。

原因:SDKはアプリがFabric内で動作していることを検出しませんでした。

Solution:

アプリのURLに?fabricEmbedded=trueを含めるか、FabricAuthOptionsにfabricEmbedded: trueを設定しましょう。

Fabric認証は状態の不一致を報告します

症状: サインインが失敗するのは、応答状態がリクエスト状態と一致しないためです。

原因: 応答は期限切れのフローや以前のサインイン試みに属します。

Solution:

Fabricのポップアップを閉じてサインインフローを再開してください。以前の試みのコールバックURLや状態値を再利用しないでください。

データモデルの問題

データAPIは展開後に内部サーバーエラーを返します

症状:npx rayfin up または npx rayfin up db apply 成功しても、GraphQLやREST data APIが内部サーバーエラーを返します。

原因:Microsoft SQL Serverでは、maxのない@text()フィールドがNVARCHAR(MAX)列を生成し、GraphQLスキーマの生成を妨げる可能性があります。

Solution:

影響を受ける各テキストフィールドに明示的な最大長さを追加します:

@text({ max: 200 })
title!: string;

次に、スキーマの変更を見直して適用します:

npx rayfin up db apply --force

Caution

--forceを使う前に報告されたすべての操作を確認してください。このオプションは恒久的なデータ損失を引き起こす可能性があります。

データサービスには方言が必要です

症状: 展開がHTTP 400応答で失敗し、 Dialect is required when Data module is enabledを報告します。

原因:services.data.enabledtrueですが、rayfin.yml方言を定義するわけではありません。

Solution:

Microsoft SQL Serverの設定:

services:
  data:
    enabled: true
    dialect: mssql

新しいエンティティはデプロイ後に利用できません

症状: デプロイは成功しますが、新規または変更されたエンティティに対するクエリは失敗したり、エンティティが存在しないかのように振る舞います。

原因: データベーススキーマがまだ適用されているか、フロントエンドが古い生成型やキャッシュ設定を使っている可能性があります。

Solution:

展開状況を確認してください:
```
npx rayfin up status
```
配属が健全になるまで待ちましょう。
フロントエンドをリフレッシュするか再構築してください。
それでもエンティティが失敗する場合は、スキーマを明示的に適用します:
```
npx rayfin up db apply
```

完全なワークフローについては、「スキーマ変更を適用し検証する」をご覧ください。

API にリレーションシップが表示されない

症状： 関連エンティティフィールドは、クエリを実行するときに使用できません。

原因： ナビゲーションデコレーターが見つからないか、スキーマが適用されませんでした。

Solution:

リレーションシップデコレーターが存在することを確認します。
```
@one(() => Notebook) notebook?: Notebook;
```
スキーマを再適用します。

承認ポリシーが機能しない

症状： ユーザーは、表示すべきではないレコードにアクセスできます。

原因： ポリシー式が正しくないか、要求名が一致しません。

Solution:

ポリシーで正しい要求名 (sub、 email、 role) が使用されていることを確認します。
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
デコードされた JWT をログに記録して、要求値がコードと一致することを確認します。

古い API 応答

症状： フロントエンドは、スキーマの変更後に古いデータ図形を返します。

原因： 生成された構成がキャッシュされます。

Solution:

バックエンドを停止します。
.temp/でrayfin/ ディレクトリを削除します。
```
rm -rf rayfin/.temp/
```
サービスを再起動し、スキーマを再適用します。

CLI の問題

コマンドが見つからない

症状：npx rayfinを実行すると、"コマンドが見つかりません" が返されます。

原因： CLI がインストールされていないか、npm が PATH にありません。

Solution:

Node.js と npm がインストールされていることを確認します。
```
node --version
npm --version
```
依存関係を再インストールします。
```
npm install
```

CLI バージョンの不一致

症状： CLI コマンドは、更新後に予期しないエラーで失敗します。

原因： キャッシュされた CLI のバージョンが古くなっています。

Solution:

更新して再インストールします。

npm update --save
npm install
npx rayfin --version

CLIのグローバル版とローカル版の不一致

症状： CLI コマンドは、プロジェクト間で予期しないエラーで失敗します。

原因： CLI バージョンのグローバルインストールとローカルインストールが一致しません。

解決策: ローカルバージョンの npm list @microsoft/rayfin-cliを検証します。現在のプロジェクトのnode_modulesのバージョンが表示されます。グローバルバージョンの npm list -g @microsoft/rayfin-cliを確認します。システム全体にインストールされているバージョンが表示されます。 rayfin CLI パッケージで npm uninstall -g を使用して、グローバルバージョンを削除し、ローカルバージョンを使用します。

秘密管理の問題

シークレットコマンドはプロンプトが出ません

症状:npx rayfin secret set <NAME> 値の指示なしに終了します。

原因: 標準入力はインタラクティブ端末ではなく、 CI 環境変数が trueに設定されている場合もあります。このコマンドはマスクされたインタラクティブプロンプトを使用します。

Solution:

非インタラクティブな秘密作成には、以下のサポート代替案のいずれかをご利用ください:

値をコマンドにパイプして、1 つのシークレットを設定します。
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```
環境ファイルから複数のシークレットを設定する:
```
npx rayfin secret set --env-file .\secrets.env
```

シェル履歴には秘密の値は含めず、ソース管理に secret.txt や .\secrets.env をコミットしないでください。

秘密指令が許可拒否を返す

症状:npx rayfin secret set または許可エラー npx rayfin secret list 返す。

原因:アプリがデプロイされていないか、サインインしたアカウントがターゲットのFabricワークスペースにアクセスできない場合があります。

Solution:

アプリをプロビジョニングするために npx rayfin up を実行してください。
npx rayfin loginを実行し、ワークスペースにアクセスできるアカウントを選択してください。
秘密のコマンドをやり直せ。

詳細については、「関数秘密の管理」を参照してください。

ビルドとパッケージ化の問題

ビルドコマンドが失敗する

症状： ビルドコマンドで出力が生成されないため、静的ホスティングのデプロイは失敗します。

原因： ビルドエラーまたは正しく構成されていないビルドコマンド。

Solution:

ビルドコマンドを手動で実行します。
```
npm run build
```
報告されたエラーを修正します。
出力フォルダーにファイルが含まれていることを確認します。

空の静的フォルダー

症状： 静的デプロイが "空のフォルダー" エラーで失敗する。

原因： 構成された folder パスが正しくありません。

Solution:

folderのrayfin.yml パスがビルド出力と一致するかどうかを確認します。

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

データベースの問題

データベーススキーマの適用失敗

症状:npx rayfin up db applyやnpx rayfin up db apply --forceを動かしても失敗します。

原因:リモートデータベースのスキーマとアプリコードで定義されたスキーマが同期していません。アプリのコードはFabricアプリの真実の情報源です。

リモートデータベーススキーマはFabricポータル、SQL Server Management Studio(SSMS)、Visual Studio CodeのSQL Server拡張機能、その他のSQLツールを通じて変更しないでください。データエンティティ内の列に対する以下の変更はサポートされていません:

コラムの名前変更。
列のデータ型を変更すること。
柱を取り除くこと。

列の追加はサポートされています。既存の列を削除または変更すると、アプリやFabricへのデプロイが壊れる可能性があります。

Solution:

リモートデータベーススキーマの手動変更をアプリコードのスキーマと一致させるように戻してください。
もしコーディングエージェントがアプリコードでサポートされていないスキーマを変更した場合は、その変更を元に戻すよう指示してください。
スキーマのapplyコマンドをもう一度実行します:
```
npx rayfin up db apply
```
列名を変更する場合は、--force によってスキーマの更新を完了できることがあります:
```
npx rayfin up db apply --force
```
Caution

--forceを使用すると、永続的なデータ損失が発生する可能性があります。提案された操作内容を確認し、データ損失リスクを受け入れていることを確認してから進めてください。

接続が拒否されました

症状： データ操作は接続エラーで失敗します。

原因： データベースコンテナーが実行されていないか、正常性チェックが失敗しました。

Solution:

コンテナーログを確認します。
```
docker compose logs -f
```
サービスを再起動します。

再起動後のデータ損失

症状： サービスを停止して開始すると、データが消えます。

原因： ボリュームは --purgeで削除されました。

Solution:

データを保持するには、--downの代わりに--purgeを使用します。

既知の制限

現在の制限事項と推奨される回避策については、次を参照してください。

count() は fluent GraphQL クライアントでは使用できません。 results.lengthを使用します。
多対多リレーションシップはサポートされていません。明示的な結合エンティティを使用します。
セッションオブジェクトは不透明であり、 isAuthenticated プロパティまたは user プロパティを確認します。
rayfin.ymlで認証を有効または無効にした後、バックエンドを再起動します。

ヘルプを取得する

問題が解決しない場合:

Fabric Apps のドキュメントを確認します。
GitHub リポジトリで既知の問題を確認します。
詳細なログと再現手順を含むバグレポートを提出します。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-29

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

デプロイメントの問題

401 または 403 エラーでデプロイが失敗する

静的デプロイがサイズ制限を超えています

静的デプロイメントにはリモートエンドポイントはありません

認証の問題

認証トークン取得の失敗

サインイン後にセッションが保持されない

Fabric SSO ポップアップがブロックされました

Fabric認証はタイムアウトします

Fabric SSOが発信元不一致を報告します

initEmbeddedAuth() は null を返します。

Fabric認証は状態の不一致を報告します

データ モデルの問題

データAPIは展開後に内部サーバーエラーを返します

データサービスには方言が必要です

新しいエンティティはデプロイ後に利用できません

API にリレーションシップが表示されない

承認ポリシーが機能しない

古い API 応答

CLI の問題

コマンドが見つからない

CLI バージョンの不一致

CLIのグローバル版とローカル版の不一致

秘密管理の問題

シークレットコマンドはプロンプトが出ません

秘密指令が許可拒否を返す

ビルドとパッケージ化の問題

ビルド コマンドが失敗する

空の静的フォルダー

データベースの問題

データベーススキーマの適用失敗

接続が拒否されました

再起動後のデータ損失

既知の制限

ヘルプを取得する

関連するコンテンツ

フィードバック

その他のリソース

`initEmbeddedAuth()` は `null` を返します。

データモデルの問題

ビルドコマンドが失敗する