Update the Browser Build errors page

Author: marionbarker

docs/browser/bb-errors.md

@@ -5,14 +5,24 @@
 
     If you are updating your build, the process can be confusing and some error messages can be misleading.
 
-    If you are having trouble, don't hesitate to ask for help.
+    You are not alone - please reach out.
 
-    Please do NOT:
+If you are having trouble:
 
-    * Spend hours in frustration
-    * Rename or delete a repository
-    * Delete your GitHub account
-    * Remove your App from App Store Connect
+#### Please DO:
+
+* [Ask a mentor for help](#where-to-get-help-with-browser-build)
+* Use the LoopDocs search feature
+* Use the zulipchat or Facebook search feature
+
+#### Please do NOT:
+
+* Search in a general internet browser to find your error
+* Ask ChatGPT (or other AI) how to fix your error
+* Spend hours in frustration
+* Rename or delete a repository
+* Delete your GitHub account
+* Remove your App from App Store Connect
 
 ### Where to Get Help with Browser Build
 
@@ -50,6 +60,90 @@ Mentors can go to your public&nbsp;_<span translate="no">GitHub repository</span
 
     All that is needed to assist is your link to the *GitHub* repository where you are building.
 
+## Quick Reference for Browser Build Errors
+
+Please make this your first stop if you get any kind of an error with Browser Build.
+
+!!! important "Check Upstream and Keep Alive Error"
+    If you have not manually updated your fork since 21 April 2025 - there is a one-time requirement to do that. Instructions and background for that step are found here:
+
+    * [Check Upstream and Keep Alive Error](#check-upstream-and-keep-alive-error)
+
+### Look at the Annotation
+
+If you get an error in an Action. Click on the link and scroll down to view the annonation. An example is shown below. Most errors have a clear annotation telling you what to do. If the annotation is not clear to your, please [ask a mentor for help](#where-to-get-help-with-browser-build).
+
+![graphic with an example validate secret error](img/example-annotation.png){width="800"}
+{align="center"}
+
+### Rebuild or New Builder
+
+* If you have successfully built before and this is a rebuild, skip ahead to [Rebuild Errors Quick Reference](#rebuild-errors-quick-reference)
+* If you are a new builder, please follow these suggestions
+
+## New Builder: Quick Reference
+
+### New Builder: Validate Secrets Error
+
+This is the first step. If you have not succeeded (&#x2705;) with this action - STOP.
+
+* No other action will work - because all the other actions include Validate Secrets as the first step
+* Be sure to [Look at the Annotation](#look-at-the-annotation)
+* You can [ask a mentor for help](#where-to-get-help-with-browser-build)
+
+If you want to try to solve it yourself, refer back to these section in the documentation:
+
+* [Collect Secrets](secrets.md){: target="_blank" }
+* [Enter the Secrets](prepare-fork.md#enter-the-secrets){: target="_blank" }
+
+### New Builder: Add Identifiers Error
+
+If you succeeded with Validate Secrets, this should also succeed. If it does not, please [ask a mentor for help](#where-to-get-help-with-browser-build).
+
+### New Builder: Create Certificates Error
+
+This is one of the hardest ones to solve. If you are getting this, don't be afraid to [ask a mentor for help](#where-to-get-help-with-browser-build). If you want to solve it yourself, a link is coming your way but first read this:
+
+#### This is NOT Your Error
+
+When you start this action, GitHub starts a cloud computer to run your job for you. It doesn't have any information about you or your secrets - yet.
+
+Early in the log file you will see two phrases in red font:
+
+> There are no local code signing identities found.
+
+> security: SecItemCopyMatching: The specified item could not be found in the keychain.
+
+This is normal. The next steps will set up a keychain for you using your Match-Secrets repository and your MATCH_PASSWORD pass phrase.
+
+#### Where to find the Certificate Solutions
+
+Head over to [Action: Create Certificate Errors](#action-create-certificates-errors) and find your specific error.
+
+### New Builder: Build Errors
+
+The most likely reason to get errors here is a mistake in the [Prepare App](prepare-app.md){: target="_blank" } page. 
+
+Common errors are:
+
+* You skipped one of the Identifiers when adding the App Group to it
+* The App Group was spelled wrong
+* You unchecked a capability on one of the Identifiers (because you watched an old video)
+* You did not select the correct identifier when creating your app
+* You entered an incorrect TEAMID
+
+All of these solutions are found in [Action: Build Loop Errors](#action-build-loop-errors). The mentors can pick out the exact solution quickly if you [ask a mentor for help](#where-to-get-help-with-browser-build).
+
+An example annotation for skipping one of the Identifiers is shown in the graphic below. The App Group for `Loop-Intent-Extension` was deliberately removed to provoke that error.
+
+![graphic with an example build error](img//example-identifier-build-errors.png){width="800"}
+{align="center"}
+
+Ignore the warnings - this does not affect the build.
+
+
+## Rebuild Errors: Quick Reference
+
 ### `Check Upstream and Keep Alive` Error
 
 !!! important "`Check Upstream and Keep Alive` Error"
@@ -70,7 +164,15 @@ Mentors can go to your public&nbsp;_<span translate="no">GitHub repository</span
 
     This affected all the Open-Source apps in our community - Loop, LoopFollow, LoopCaregiver, Trio, iAPS and xDrip4iOS. The developers in our community have restored the ability to build using the Browser Build method. Stay tuned for updates to required actions in the documentation over the next few months, before we hit the 60 day limit.
 
-### Most Common Mistakes
+### Rebuild: Create Certificates Error
+
+With `Loop 3.6.0`, these should be a thing of the past - but you must first manually update (sync) your repository in order to get this feature added and you must do this new step [Add Variable](prepare-fork.md#add-variable){: target="_blank" }
+
+### Rebuild: Build Error
+
+After you update to `Loop 3.6.0`, the Create Certificates Action is incorporated into the Build Action. So for rebuilders, if you completed the manual sync and added the new variable, you should not get an error when building.
+
+## Most Common Mistakes
 
 If you get an error when building with a browser, you can use this page to figure out what to do - but don't be afraid to [ask for help](#help-with-errors).
 
@@ -97,12 +199,6 @@ These are some of the most common errors to date.
     * You can delete any branch that starts with the name `alive` and try again
     * See [Automatic Creation of `alive branch`](automatic.md#automatic-creation-of-alive-branch){: target="_blank" }
 
-## Error Annotations
-
-Error annotations are available for the *Loop* app released version 3.4 and later. These were contributed by community volunteers along with the improvements to enable automatic updates and automatic builds.
-
-Not all error messages have an annotation yet. In those cases, you will be required to search for the error string as explained in [Find the Error](#find-the-error).
-
 ## Examine Annotation
 
 If a&nbsp;<span translate="no">*GitHub* Action</span>&nbsp;fails, you will see a clear notification.
@@ -125,7 +221,9 @@ Notice that&nbsp;<span translate="no">*GitHub* Action: 1. Validate Secrets</span
 
 ### Annotation without Clear Message (*Certificates*)
 
-Not all error messages have a clear annotation (yet).
+This section is left here for those who have an older version (3.4 or older) in their fork. If that is you, please follow these directions, [Rebuild Errors: Quick Reference](#rebuild-errors-quick-reference) and ignore this section.
+
+Not all error messages have a clear annotation (up through version 3.4.x).
 
 For example, the graphic below shows a failure of&nbsp;<span translate="no">*GitHub* Action: 3. Create Certificates</span>&nbsp;.
 
@@ -166,7 +264,7 @@ The GIF below shows a failure of&nbsp;_<span translate="no">*GitHub* Action: 4.
 
 This section is required when you need to search for a string to diagnose and error that does not have a clear annotation.
 
-## Misleading Error Message
+### Misleading Error Message
 
 If there are *Apple* Developer agreements you have not accepted, you may get errors when you try to Build that indicate your *Apple* <code>Secrets</code> are incorrect even if they are not.
 
@@ -182,6 +280,8 @@ You can also get this message if the credit card used to purchase the Developer
 
 ## Find Your Error
 
+At this point, it may be faster to [ask a mentor for help](#where-to-get-help-with-browser-build). But if you want to dig into the details of the log and find the error yourself, the information is here.
+
 There is a separate section for each step in the process. First, you must follow the [Examine Annotation](#examine-annotation) instructions to view the record of the failed action. Then go to the section for the Action you were trying to complete to look for possible error strings to copy into the search box. For each section there are possible strings to paste to search the log.
 
 * Paste in a possible error string (copy it exactly); repeat until you find a match
@@ -258,9 +358,23 @@ For Version 3.4 and later - use [Examine Annotation](#examine-annotation) and re
 
 ## Action: `Create Certificates` Errors
 
-Review [Examine Annotation](#examine-annotation) for instructions on how to use the error strings.
+> Reminder - If it is not obvious to you what your error is, please [ask a mentor for help](#where-to-get-help-with-browser-build)
+
+> * you might get to the answer sooner
+> * you are less likely to do something that makes it harder for the mentor to help you later
 
-### Error: Wrong TEAMID in `Secrets`
+Review [Find the Error](#find-the-error) for instructions on how to use the error strings.
+
+List of certificate errors on this page:
+
+* [Error: No profile for team](#error-no-profile-for-team)
+* [Error: Error cloning certificates](#error-error-cloning-certificates)
+* [Error: Could not decrypt](#error-could-not-decrypt)
+* [Error: Could not create](#error-could-not-create)
+ 
+### Error: No profile for team
+
+This happens if you entered the wrong TEAMID in `Secrets`.
 
 Copy the words on the line below and paste them into the search function for your action log.
 
@@ -326,7 +440,9 @@ Follow the [Configure to Use Browser: Create Loop App in App Store Connect](prep
 
 You should be able to continue with the [Configure to Use Browser Steps to `Create Certificates`](certs.md#create-certificates) and then proceed from there with `Build Loop` and keep going.
 
-### Error: Missing Repository Access
+### Error: Error cloning certificates
+
+This indicates you do not have the appropriate Repository access.
 
 Copy the words on the line below and paste them into the search function for your action log.
 
@@ -362,6 +478,22 @@ After you have clicked `Update token` you should see the token overview again wi
 
 You should be able to continue with the [Configure to Use Browser Steps to `Create Certificates`](certs.md#create-certificates) and then proceed from there with `Build Loop` and keep going.
 
+### Error: Could not decrypt
+
+Copy the words on the line below and paste them into the search function for your log file.
+
+> ``` { .text .copy }
+> decrypt the repo
+> ```
+
+The full error message is:
+
+> `Couldn't decrypt the repo, please make sure you enter the right password`
+
+If you know you entered the incorrect <code>MATCH_PASSWORD</code> in your repository <code>Secrets</code>, go and fix it now and try again.
+
+Otherwise, you need to follow the steps to [Reset Match-Secrets](#reset-match-secrets).
+
 ### Error: Could not create
 
 Copy the words on the line below and paste them into the search function for your log file.
@@ -376,9 +508,9 @@ The full error message is:
 
 #### New with `Loop 3.6.0`
 
-> If you just updated to 3.6.0 (once it is released), you might not have added the new variable, `ENABLE_NUKE_CERTS`. Go do that now and then try again. It will take care of renewing your certificates automatically. See [Add Variable](prepare-fork.md#add-variable){: target="_blank" }.
+> If you just updated to 3.6.0, you might not have added the new variable, `ENABLE_NUKE_CERTS`. Go do that now and then try again. It will take care of renewing your certificates automatically. See [Add Variable](prepare-fork.md#add-variable){: target="_blank" }.
 
-These steps are needed to make room for a `Certificate` when running versions earlier than 3.6.0:
+These steps are only needed to make room for a `Certificate` when running versions earlier than 3.6.0 if you choose not to add the `ENABLE_NUKE_CERTS` variable:
 
 1. Delete an old `Distribution Certificate`
     * *Apple* limits you to two `Distribution Certificates`
@@ -395,24 +527,10 @@ These steps are needed to make room for a `Certificate` when running versions ea
 !!! question "But what about *TestFlight* builds?"
     Previous builds using this method that are already in *TestFlight* are not affected by deleting the `Distribution Certificate`.
 
-### Error: Could not decrypt
-
-Copy the words on the line below and paste them into the search function for your log file.
-
-> ``` { .text .copy }
-> decrypt the repo
-> ```
-
-The full error message is:
-
-> `Couldn't decrypt the repo, please make sure you enter the right password`
-
-If you know you entered the incorrect <code>MATCH_PASSWORD</code> in your repository <code>Secrets</code>, go and fix it now and try again.
-
-Otherwise, you need to follow the steps to [Reset Match-Secrets](#reset-match-secrets).
-
 ## Action: `Build Loop` Errors
 
+This is the section for people who have not successfully built the *Loop* app one time. If you are a repeat builder, please skip ahead to [Repeat Build Loop Errors](#repeat-build-loop-errors).
+
 !!! warning "Run `Create Certificates` First"
     When running a version earlier than `Loop 3.6.0`, you must run Action: `Create Certificates` before attempting to run Action: `Build Loop`
 
@@ -427,6 +545,13 @@ Refer to [Annotation without Clear Message (*Build*)](#annotation-without-clear-
 
 For each section below, copy the phrase into the search function of the log. If you find it, solve that error. If not, move on to the next one.
 
+List of build errors in this section:
+
+* [`Error: Could not find an app on App Store Connect`](#error-could-not-find-an-app-on-app-store-connect)
+* [`Error: Provisioning Profile`](#error-provisioning-profile)
+* [`Error: A new one cannot be created because you enabled`](#error-a-new-one-cannot-be-created-because-you-enabled)
+
+
 ### `Error: Could not find an app on App Store Connect`
 
 Copy the words on the line below and paste them into the search function for your action log.
@@ -517,7 +642,7 @@ Use the [Examine Annotation](#examine-annotation) instructions to find your erro
 
 ### `ERROR: Asset validation failed`
 
-This error indicates your fork needs to be updated. As of 29 April 2024, you are required to use Xcode 15 to build the app.
+This error indicates your fork needs to be updated. As of 24 April 2025, you are required to use Xcode 16 to build the app.
 
 There are serveral phrases you can check for. All of them have the same solution.