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

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

このページでは、Pipeline の実行失敗やその他の一般的な問題に対するセルフサービスのトラブルシューティングの手順をご紹介します。


シナリオ 1: 以前はビルドが成功していたが、最近失敗するようになった

考えられる原因:

  • コードの変更

  • ベンダーによるビルド イメージの変更

  • ワークスペース/リポジトリ/デプロイメントの変数の変更

  • サードパーティーの依存関係の停止/変更

  • Bitbucket の停止

  • Pipeline インフラストラクチャの変更

トラブルシューティング手順

ビルド番号を選択して、[Rerun] ボタンをクリックして前回成功したビルドを再実行します。再実行でまだ成功しますか。

はい (tick)

  • 成功したビルドと失敗したビルドの間でのコードの違いを確認し、ビルドが失敗した理由を調査します。

いいえ (error)

  • Abstract Bitbucket pipelines infrastructure and test build locally by following the steps outlined on Troubleshoot failed pipelines locally with Docker.

    • 同じビルドがローカルで失敗した場合、これは Bitbucket Pipeline のインフラストラクチャまたは構成の問題ではないため、このビルドを Docker で正常に実行できるようになるまでトラブルシューティングの手順を続ける必要があります。

    • Docker を使用してローカルでテストするときに同じビルドが成功した場合は、サポート チケットを起票し、ローカルで実行したビルドのログを共有してください。

  • Other things to consider

    • ビルド ログのBuild setup セクションで、成功したビルドと失敗したビルドの間でビルド イメージ SHA (例: build :docker.io/library/python@sha256:03ac9e...) を比較します。Build setup セクションは、Pipeline ログの Build タブの最初のセクションとして見つけることができます。変更がある場合には、「Docker イメージをビルド環境として使用する」に従って、bitbucket-pipelines.yml を正確な SHA イメージを固定して、ビルド成功時の画像ハッシュを使用し、ビルドを実行します。

    • ワークスペース、レポジトリ、デプロイメント変数に最近変更があったかを確認してください。変更があった場合には、前の変数の値を使用し、失敗したビルドを再実行してください。

    • サードパーティー プラットフォームをイメージに使用していますか。使用している場合は、適切なステータス ページを確認して停止していないか確認してください。主要なサードパーティーのイメージ プラットフォームへのリンクの一覧は以下の通りです。サードパーティーのサポートチームに問い合わせていただく必要があります。

    • 他の依存関係にも変更がある可能性があります。パッケージがたとえば via apt、yum、apk などのコマンドを使ってインストールされた場合には、コードの依存関係が変わっている可能性があるため、バージョンを固定します。

    • Bitbucket Cloud に障害が発生している、または、発生していたかを、Bitbucket ステータスページで確認します。実行失敗の原因となりうるインシデントがある場合は、インシデントが解決された後に失敗したビルドを再実行します。

    • 最近 Bitbucket Pipelines に変更がなかったか、「Bitbucket のインフラストラクチャの変更」を確認します。推奨事項の記載があれば、それに従います。


シナリオ 2: Pipeline ビルドが「Container “Build” exceeded memory limit」エラーで失敗する

シナリオ 2.1: 一般的なシナリオ

考えられる原因:

  • ビルドに、許可されているビルド コンテナー メモリを超えるメモリが必要となっている。

トラブルシューティング手順

「Docker でパイプラインのデバッグをローカルで行う」ページの手順を使ってビルドをローカルでデバックします。注意: macOS ではスワップメモリを 100 Mb 以下に設定できないため、メモリ制限の問題をローカルでデバッグできません。同じようなメモリエラーによってビルドがローカルで失敗しますか。

はい (tick)

  • Pipeline で以下のコマンドを実行し、どのプロセスがより多くのメモリを消費しているかを観察します。これにより、問題を絞り込み、原因を特定し、対策を講じることができます。

- while true; do echo "Memory usage in bytes:" && cat /sys/fs/cgroup/memory.current; echo "Swap memory usage in bytes:" && cat /sys/fs/cgroup/memory.swap.current; sleep 2; done &
- while true; do date && ps aux && echo "" && sleep 2; done &

いいえ (error)

シナリオ 2.2: Jest Test Framework を使用したビルドが遅い、または頻繁にハングする (Pipeline のビルド分消費量に基づく)、または、「Container “Build” exceeded memory limit 」エラーで失敗する。

考えられる原因:

  • 多数のワーカーが同時に動いている

トラブルシューティング手順

Pipeline で test コマンドが開始する直前の、プロセスのリストおよびバックグラウンドのメモリ使用量を表示します。

- while true; do ps -aux && sleep 5; done &
- while true; do echo "Memory usage in megabytes:" && echo $((`cat /sys/fs/cgroup/memory.current | awk '{print $1}'`/1048576)) && sleep 0.1; done &

プロセス一覧の出力には、ビルドが遅いとき、または OOM (メモリ不足) になったときに実行されているワーカーの数が表示され、ワーカー プロセスとともに CPU とメモリの使用状況を確認できます。

出力には、CPU / メモリ使用率が高い 4〜7 個のワーカー プロセスが表示されますか。

はい (tick)

  • JEST はデフォルトで 7 個の子ワーカーを作成し、Jest Test を呼び出すデーモン プロセスがこれらの各 Jest ワーカーにメモリを割り当てます。(例えば) ワーカーあたり最大 2 GB が構成されており、これらのワーカー 7 個のすべてが同時に実行されている場合、簡単に OOM (メモリ不足) に達する可能性があります。その結果、ビルドコンテナに十分なメモリが割り当てられないため、ビルドの動作が遅くなったり、停止したように見えたりすることがあります。この問題を解決するには、以下の手順に従ってください。

    • build コマンドに、コマンド 「--maxWorkers=2」を追加して、ワーカーの数を2 に制限します。

    • または、「Configuring Jest」ページで説明されているように、package.json や jest config で定義できるはずです。

いいえ (error)


シナリオ 3: Pipelinesのビルドが失敗し、ビルド ログに以下のエラーが表示される

<command_name>: Command not found

考えられる原因:

  • pipeline 変数の 1 つに PATH 変数が定義されている。

トラブルシューティング手順

PATH 変数が、Workspace、Repository、または Deployment 変数に定義されていますか。

はい (tick)

  • Workspace、Repository、または Deployment の変数にPATHという名前の変数を定義すると、ビルド イメージのデフォルトの $PATH 変数が上書きされ、以下のエラーが発生します。

    <command_name>: Command not found

  • この問題を解決するには、「PATH」という名前の変数で workspace、repository、および deployment 変数セクションに使用することを避けてください。その変数の使用用途がわかるような、より詳細な名前を使うようにしてください (例: remote_path、web_path、destination_path など)。

  • 補足: BCLOUD-20162 では、Pipeline の変数ページで、変数名として「PATH を使用しないように注意喚起する機能要望を追跡しています。

いいえ (error)

  • ビルドで実行しているコマンドは、ビルド イメージにインストールされていますか。インストールされていない場合には、ビルド イメージにコマンドをインストールしてください。コマンドがインストールされていてもエラーが出る場合には、サポートチケットを起票 して、Pipeline ビルドの URL を bitbucket.org から共有してください。


Scenario 4: Bitbucket pipeline is failing with Exceeded build time limit error.

考えられる原因:

  • Pipeline ビルドに時間のかかるプロセスがある

トラブルシューティング手順

パイプラインのビルドに時間のかかっているプロセスがないか確認します。各 build コマンドの前と後に date +"%T" コマンドを実行し、どのプロセスが pipeline で予想以上に時間がかかっているかを確認します。また、Docker でパイプラインのデバッグをローカルで行う」ページの手順に沿ってローカルでビルドをテストし、コマンド「date +"%T"」を使ってどのプロセスが長い時間がかかっているのかを確認します。

Pipeline とローカル ビルドで、処理に同じような時間がかかっていますか。

はい (tick)

  • プロセスを調査し、長時間実行している理由を特定します。使用されているコマンドや技術を基にオンライン リソースを活用して、プロセスの所要時間を短縮するためにどのような対策を講じることができるかを確認します。

  • Increase the max-time property for the build step or option as mentioned in the max-time section of Configure bitbucket-pipelines.yml page. (By default this is set to 120 minutes).

  • ユーザーの操作を待っているコマンドがある場合、これらのコマンドが非対話モードで実行されるようにしてください。

  • Increase the build container memory size to 2x, 4x, or 8x as mentioned in the size section of Configure bitbucket-pipelines.yml page

  • If the total build time is unable to be reduced, please raise a Support Ticket mentioning the workspace name and the use case of running the step for longer. The Support team will exempt to run the step for more time, if possible.

いいえ (error)


シナリオ 5: ビルド技術およびテスト フレームワーク

シナリオ 5.1: Yarn でパッケージをインストールする際にネットワーク接続の問題が発生し、ビルド ログに以下のエラーのいずれかが表示される。

error An unexpected error occurred: "https://registry.yarnpkg.com/@material-ui/core/-/core-4.11.3.tgz: ESOCKETTIMEDOUT".
info There appears to be trouble with your network connection. Retrying...
 "ENOENT: no such file or directory"

考えられる原因:

  • パッケージ サイズが大きい

  • ネットワーク接続が遅い

  • 複数のパッケージのインストールプロセスが同時に実行されている

トラブルシューティング手順

ビルドログにて、yarnレジストリへの接続中に(下記のように) Timeout エラーが発生していますか。追加のビルド ログを表示するには、詳細な出力を追加する必要がある場合があります。

error An unexpected error occurred: "https://registry.yarnpkg.com/<package>: ESOCKETTIMEDOUT".
info There appears to be trouble with your network connection. Retrying...

はい (tick)

  • インストールされるパッケージが大きすぎるか、ネットワーク接続が遅すぎるために、デフォルトの NETWORK_TIMEOUT の設定が 30 秒だとパッケージ/依存関係をダウンロードできない可能性があります。タイムアウト時間を長くするために、--network-timeout パラメーターにより大きな値を指定して追加します。たとえば、タイムアウトを 300,000 ミリ秒 (5分) に設定します。

    yarn add <yourPackage> --network-timeout 300000

  • 以下のエラーで yarn install が失敗しますか。 

    "ENOENT: no such file or directory"

はい (tick)

  • デフォルトでは、yarn は 50 個の同時リクエストを許可します。代わりに、パッケージを順次インストールするように yarn を設定できます。--network-concurrency 1 を yarn install コマンドに追加します。以下に例を示します。 

yarn install --network-concurrency 1

いいえ (error)

シナリオ 5.2: Gradle テストのビルド ログに次のエラーが表示される

org.gradle.api.internal.tasks.testing.TestSuiteExecutionException:
Could not complete execution for Gradle Test

考えられる原因:

  • ワーカー プロセスの JVM のメモリが不足している。

  • テストの実施に Gradle を使用している場合には、Gradle デーモンおよび Gradle ワーカーの 2 つの主要プロセスがあります。デーモンおよびワーカーは、JVM のメモリ割り当てを別々に処理します。

トラブルシューティング手順

Gradle テストコマンドに、--stacktrace または --debug を追加します。

JVM から、以下のメモリ不足エラー (OutOfMemoryError) が返ってきますか。

org.gradle.api.internal.tasks.testing.TestSuiteExecutionException: 
Could not complete execution for Gradle Test

[DEBUG] [TestEventLogger] java.lang.OutOfMemoryError: Java heap space

はい (tick)

  • デフォルトでは、Gradle ワーカーの maxHeapSize は 512m ですが、テスト実行でこれを超えています。

  • これを解決するには、ワーカー/テスト向けの JVM のメモリ割り当てをより高い値に設定します。設定は、Gradle テストページのテスト設定で行います。

いいえ (error)


Scenario 6: Pipeline build failed with "Step exceeded processing limits and has timed out" error

シナリオ 6.1: 一般的なシナリオ

考えられる原因:

  • The maximum length of all combined pipeline variables' names and values has been exceeded, the current limit is 120k.

トラブルシューティング手順

Get the Repository, Workspace, and Deployment Variables and their values. Combine all the variable names and values together and verify the concatenated data length. Is the combined size of variable names and values more than 120k characters combined?

はい (tick)

  • Currently, when a build has multiple variables configured (including Repository, Workspace, and Deployment Variables) and has more than a total of 120k characters combined, it could cause the pipeline build to be in a stalled state or fail with the above error message.

  • To fix the issue, reduce the size of the variables to keep them under a total of 120k characters combined.

  • 補足: BCLOUD-20105 にて、このような場合に UI にエラーを通知する機能要求を追跡しています。

いいえ (error)


シナリオ 7: アーティファクトに関連する問題

シナリオ 7.1: パイプライン ステップで、前のステップで生成されたアーティファクトを見つけることができない。

考えられる原因:

  • 圧縮後のアーティファクトサイズが 1 GBを超えている。

トラブルシューティング手順

アーティファクトを生成するビルド ステップの Build teardown フェーズで、圧縮後のアーティファクトのサイズを確認します。 以下のスクリーンショットのように、アーティファクトのサイズが 1 GB を超えていますか。

はい (tick)

  • 圧縮後に 1 GB 未満のアーティファクトのみが保存されます。この制限については、「アーティファクトの使用」ページに記載があります。アーティファクトのサイズを制限値以下になるように小さくしてください。

いいえ (error)

シナリオ 7.2: パイプライン ステップで、前のステップで生成されたアーティファクトから特定のファイルを見つけることができない。

考えられる原因:

  • アーティファクト ファイルが $BITBUCKET_CLONE_DIR ディレクトリにない。

トラブルシューティング手順

アーティファクトを生成するビルド ステップ で、ls -lR <directory> コマンドを実行します。ここで、<directory> は、アーティファクトとして保存されているディレクトリです。コマンドは、アーティファクトが生成された後に実行する必要があります。

コマンドの出力結果、または、$BITBUCKET_CLONE_DIR ディレクトリにファイルが存在しますか。例: 

pipelines:
  default:
    - step:
        name: Build and test
        image: node:10.15.0
        script:
          - npm install
          - npm test
          - npm run build
          - ls -lR dist # identify all files inside dist directory
          - ls -lR reports # identify all files inside reports directory
        artifacts: # defining the artifacts to be passed to each future step.
          - dist/**
          - reports/*.txt

はい (tick)

いいえ (error)

  • アーティファクト ファイルは、BITBUCKET_CLONE_DIR からの相対で、BITBUCKET_CLONE_DIR ディレクトリ内のファイルのみがアーティファクトとして設定できます。また、アーティファクト ディレクトリとして設定されたディレクトリの中にあるファイルが保存されます。すべてのアーティファクト ファイルが BITBUCKET_CLONE_DIR の相対となっており、すべてのファイルがアーティファクト ディレクトリとして設定されたディレクトリの中にあるようにしてください。


シナリオ 8: Pipeline ビルドのキャッシュに関連する問題

シナリオ 8.1:

考えられる原因:

  • 圧縮後のキャッシュのサイズが 1 GB を超えている。

トラブルシューティング手順

キャッシュを生成するビルドステップの Build teardown フェーズから、圧縮後のキャッシュのサイズを確認します。以下のスクリーンショットのように、キャッシュのサイズが 1 GB を超えていますか。

はい (tick)

  • 圧縮後に 1 GB 未満のキャッシュのみが保存されます。この制限については、「キャッシュ」ページに記載があります。キャッシュのサイズを制限値以下になるように小さくしてください。

いいえ (error)

シナリオ 8.2: Docker イメージのビルドが、以前のビルドで生成された Docker キャッシュを使用していない。

考えられる原因:

  • Dockerfile に変更があった。

トラブルシューティング手順

キャッシュが機能しなくなった後に、Dockerfile に変更があったかどうかを確認します。変更はありましたか。

はい (tick)

  • Pipeline は、各イメージレイヤーを Docker キャッシュに保存します。キャッシュが保存された後に Dockerfile が変更された場合、その中間レイヤーの署名が変更され、既存の保存された Docker キャッシュはイメージ構築時に利用されません。

  • この問題を解決するには、Pipelines で既存のキャッシュを削除し (Pipelines > Caches > Delete)、ビルドをトリガーして新しいキャッシュを生成して保存します。この新しいキャッシュは、イメージを構築する際に、その後のビルドで使用することができます。

いいえ (error)


シナリオ 9: Git サブモジュールが pipeline ビルドでクローンされない。

考えられる原因:

  • サブモジュールが自動的にクローンされない。

トラブルシューティング手順

ビルド時にサブモジュールが明示的にクローンされているかどうかをチェックします。サブモジュールは、明示的にクローンされていますか。

はい (tick)

いいえ (error)

  • Pipelines はサブモジュールリポジトリを自動的にクローンしません。以下のように、有効な認証情報（SSHまたはHTTPSのいずれか）を使って、手動で Pipelines 設定してサブモジュールを更新する必要があります。 

    [...]
  script:
    #HTTPS     
     - >-
       git config --file=.gitmodules submodule.Submod.url https://$USERNAME:$PASSWORD@bitbucket.org/team/repo.git 
       && git submodule update --init
    #SSH
    - git config --file=.gitmodules submodule.Submod.url ssh://git@bitbucket.org/team/repo.git && git submodule update --init


シナリオ 10: ビルドセットアップに予想以上に長い時間がかかる

考えられる原因:

  • リポジトリまたはイメージのビルドサイズが大きすぎる。

トラブルシューティング手順

リポジトリをクローンしてローカルに画像を pull し、かかった時間を観察してください。Pipeline と同様の時間がかかっていますか。

イメージを pull するコマンド: docker pull [OPTIONS] NAME[:TAG|@DIGEST]

レポジトリをクローンするコマンド:

HTTPS 経由でのクローン

$ git clone https://username@bitbucket.org/teamsinspace/documentation-tests.git

SSH 経由でのクローン

$ git clone ssh://git@bitbucket.org:teamsinspace/documentation-tests.git

はい (tick)

いいえ (error)


シナリオ 11: 特定のコミットに対してビルドがトリガーされなかった

考えられる原因:

  • There is no definition on the bitbucket-pipelines.yml file that matches the branch that is receiving a Git push. It's also important to double-check the bitbucket-pipelines.yml file for spelling mistakes, as the branch name in the bitbucket-pipelines.yml file needs to match the name of the branch on the Bitbucket repository exactly for the build to be triggered.

  • push に5 個を超える参照 (ブランチ、タグ、ブックマーク) がある。

  • The push contained multiple commits at once. Pipelines will only trigger builds for the HEAD of the current Git push, meaning that, if a user pushes there commits together, only the latest will trigger a build.

  • Webhook のサイズ (コミットサイズに基づく) が 256 Kb 以上である。

トラブルシューティング手順

Did the push have more than 5 references or was the webhook larger than 256Kb?

はい (tick)

  • Push に5 個を超える参照がある。

    • 同じpush (ブランチ、タグ、ブックマーク) 上で 5 個を超える参照がある場合、Pipelines はビルドを実行しません。この制限事項は、「Bitbucket Pipelines の制限事項」ページに記載されています。

    • 必要に応じて、自動的にトリガーされなかったビルドを次の方法で手動で実行できます。

      • Branches ビューから、pipeline を手動で実行する。

      • Commits ビューから pipeline を手動で実行する。

      • Pipeline ページセクションから pipeline を手動で実行する。

      手動で pipeline を実行する方法の詳細は、「Pipeline トリガー」を参照してください。

    • 今後のビルドがトリガーしない状況を避けるためには、1 回の push での参照数 (ブランチ、タグ、ブックマーク) を減らします。

  • Webhook のサイズが 256 kb よりも大きい。

    • コミット メッセージが大きすぎて、また「Bitbucket Pipelines の制限事項」に記載の通り Bitbucket でサポートされていない場合、結果として 256 Kb 制限を超える Webhook が生成される可能性があります。

    • 必要に応じて、自動的にトリガーされなかったビルドを次の方法で手動で実行できます。

      • Branches ビューから、pipeline を手動で実行する。

      • Commits ビューから pipeline を手動で実行する。

      • Pipeline ページセクションから pipeline を手動で実行する。

      手動で pipeline を実行する方法の詳細は、「Pipeline トリガー」を参照してください。

    • 今後のビルドがトリガーしない状況を避けるためには、コミット サイズを小さくしてください。

いいえ (error)


Scenario 12: Pipeline build failed with Container “Docker” exceeded memory limit error

考えられる原因:

  • The docker service container in the Pipeline build requires more than the currently allocated memory.

トラブルシューティング手順

Was the pipeline YAML already configured to allocate more than the default 1GB of memory to the docker service?

Please note that increasing the Pipeline build step size to 2x, 4x, or 8x (using the size attribute) will not automatically increase the memory allocated to the Docker service container. Docker service with size 2x, 4x, or 8x will still be allocated 1GB of memory by default, unless you configure and allocate more memory explicitly in the YAML file (an example is given below)

はい (tick)

いいえ (error)

  • A custom memory value can be configured to the docker service to increase it further than 1GB by adding the below definition in your YAML file : 

    definitions:
  services:
    docker:
      memory: 3072 # Memory in MB -  allocate 3GB (3072MB) of memory to docker service

    Docker service can be configured to use up to:

    • 3 GB (3072 MB) of memory in regular 1x steps.

    • 7 GB (7168 MB) of memory in 2x steps.

    • 15 GB (15360 MB) of memory in 4x steps.
    • 31 GB (31744 MB) of memory in 8x steps.
  • Pipes internally use the docker service. The memory-related issues with pipes can also be fixed by assigning more memory to the Docker service.
  • It's also possible to configure multiple docker services with different memory limits if you have some specific requirements.

Scenario 13: Pipeline build failed with "unexpected system error that may have left your step half-completed"



原因:

  • This is most commonly encountered with builds that utilise runners, the error message indicates that the Runner step container was evicted mid-build

トラブルシューティング手順

When a step is evicted mid-build, the job retry process will try to restart it. Unfortunately, steps are idempotent - this means that Pipelines cannot retry things that were half completed automatically as it doesn't know where or how it failed, and requires user intervention to determine whether to retry.

You will need to re-run the build - does it complete this time?

はい (tick)

  • Continue to monitor your builds in case it becomes a frequent occurrence, in which case you will need to:
    1. Raise a Support Ticket  
    2. Share the Pipeline build URL from bitbucket.org
    3. Attach any Pipelines Runner logs to the support ticket

いいえ (error)



最終更新日: 2025 年 1 月 22 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

このセクションの項目

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.