Install Copilot on MacOS: Command Line Tools are too outdated

[natsuto6]

ActualResult

1. Execute brew install aws/tap/copilot-cli.
2. An error message is output indicating that the Command Line Tools are outdated.

   ...
   ...
   Error: Your Command Line Tools are too outdated.
   ...

Steps to Resolve the Issue

1. Checked in Mac system settings to confirm that no software update is required.
2. Executedsudo rm -rf /Library/Developer/CommandLineToolsin the terminal, entered the password, and removed the Command Line Tools.
3. Executedsudo xcode-select --installin the terminal, a dialog box appeared, and agreed to the terms and conditions to install new Command Line Tools.
4. Executedbrew install aws/tap/copilot-cliagain to complete the installation.

• System Information macOS Ventura 13.5.1

Expected behavior

• Add specific instructions for handling the error message to the documentation.
• Add steps for checking for software updates or commands to update the system.

[kou]

Could you show full log instead of extracted one? (It seems that it's a Homebrew related problem not aws/copilot-cli related.)

[natsuto6]

Thanks for your response. I understand that this is primarily a Homebrew issue. However, I believe a brief note in the Copilot CLI documentation could help users like me who encounter this issue.

Here's the complete log as you requested:

❯ brew install aws/tap/copilot-cli
Running `brew update --auto-update`...
==> Auto-updated Homebrew!
Updated 3 taps (homebrew/services, homebrew/core and homebrew/cask).
==> New Formulae
asn                       fwupd                     ldid-procursus            powerlevel10k             python-pyproject-hooks
chaoskube                 gickup                    libgit2@1.6               pwned                     python-pytz
cloudfox                  gismo                     libjcat                   pystring                  spacer
cryptopp                  gitea                     libxmlb                   python-click              talhelper
eza                       jr                        meson-python              python-mutagen            tf-profile
falco                     json2ts                   mgis                      python-pycurl             uhdm
falcoctl                  kosli-cli                 orbiton                   python-pyparsing          woodpecker-cli
==> New Casks
aifun           clickhouse      hhkb            kreya           monotype        recipeui        rippling        zui

You have 65 outdated formulae installed.

==> Tapping aws/tap
Cloning into '/usr/local/Homebrew/Library/Taps/aws/homebrew-tap'...
remote: Enumerating objects: 6832, done.
remote: Counting objects: 100% (6832/6832), done.
remote: Compressing objects: 100% (1297/1297), done.
remote: Total 6832 (delta 5489), reused 6770 (delta 5464), pack-reused 0
Receiving objects: 100% (6832/6832), 961.84 KiB | 4.49 MiB/s, done.
Resolving deltas: 100% (5489/5489), done.
Tapped 21 formulae (56 files, 1.2MB).
==> Fetching aws/tap/copilot-cli
==> Downloading https://github.com/aws/copilot-cli/releases/download/v1.30.1/copilot_1.30.1_macOS_amd64.tar.gz
==> Downloading from https://objects.githubusercontent.com/github-production-release-asset-2e65be/202018792/cfdd948d-f1c0-487b-8271
############################################################################################################################ 100.0%
==> Installing copilot-cli from aws/tap
Error: Your Command Line Tools are too outdated.
Update them from Software Update in System Settings.

If that doesn't show you any updates, run:
  sudo rm -rf /Library/Developer/CommandLineTools
  sudo xcode-select --install

Alternatively, manually download them from:
  https://developer.apple.com/download/all/.
You should download the Command Line Tools for Xcode 14.3.

I think a small note in the documentation suggesting what steps to follow if someone encounters this Homebrew issue would improve the user experience. It's just a suggestion to make the installation process smoother for new users.

[kou]

Thanks.

It seems that the log shows what users should do when this error is happen:

If that doesn't show you any updates, run:
  sudo rm -rf /Library/Developer/CommandLineTools
  sudo xcode-select --install

Alternatively, manually download them from:
  https://developer.apple.com/download/all/.
You should download the Command Line Tools for Xcode 14.3.

Do you suggest that we should copy the message to https://github.com/aws/copilot-cli#installation ? Or do we just need a small note something like "You must read error message carefully when you get an error"?

[natsuto6]

Thank you for your response.

I think a small note like "You must read the error message carefully when you encounter an error" could suffice. The error message is indeed self-explanatory, but reminding users to pay attention to it can prevent unnecessary confusion or issue reports.

Looking forward to your thoughts.

[kou]

Thanks for clarifying it. Let's wait for a response from maintainers.

[Lou1415926]

Hey @natsuto6 👋🏼 Thanks for opening the issue and thank you @kou for chiming in!

I am all for helpful documentation🤝! I wonder though, when people see an issue from brew install aws/tap/copilot-cli, how often do they think of checking our documentation?

Basically, I feel like the proposed message is only helpful if people think about checking Copilot's documentation - as well as reading it carefully - when they see brew install error. I suspect that in reality, people typically just Google it, instead of looking at our documentation😞.

In addition, ideally I want to keep Copilot documentation to contain only Copilot-related information. The solution to "Command Line Tools are too outdated" is out of our control (mostly depends on Apple), and it is entirely possible to change in the future - and at that time, we would end up having outdated instruction on our doc page, which would further confuse people.

A few things I propose to do, instead of adding the message to documentation:

1. Rename this issue to "Install Copilot on MacOS: Command Line Tools are too outdated", so that this issue is more likely to show up when people search on Google.
2. Mark this issue as "Guidance" to further increase the chance that people find this issue.

Hope this sounds good to you!! Please me know if you have other thoughts!

[natsuto6]

Hey @Lou1415926 , thanks for your thoughtful response!

I completely understand your concerns about keeping the Copilot documentation focused and up-to-date. Your proposed solutions, renaming the issue and marking it as "Guidance", seem like a balanced approach to aid those who run into this specific error.

I agree with this approach. Please go ahead and implement the changes.

Thank you for considering my suggestion and coming up with a reasonable alternative!

[github-actions[bot]]

This issue is stale because it has been open 60 days with no response activity. Remove the stale label, add a comment, or this will be closed in 14 days.

[github-actions[bot]]

This issue is closed due to inactivity. Feel free to reopen the issue if you have any further questions!