diff --git a/cli/dotfiles.go b/cli/dotfiles.go
index 8d331d988d53b..60be52a0fc629 100644
--- a/cli/dotfiles.go
+++ b/cli/dotfiles.go
@@ -193,6 +193,18 @@ func (r *RootCmd) dotfiles() *clibase.Cmd {
 				}
 
 				_, _ = fmt.Fprintf(inv.Stdout, "Running %s...\n", script)
+
+				// Check if the script is executable and notify on error
+				scriptPath := filepath.Join(dotfilesDir, script)
+				fi, err := os.Stat(scriptPath)
+				if err != nil {
+					return xerrors.Errorf("stat %s: %w", scriptPath, err)
+				}
+
+				if fi.Mode()&0o111 == 0 {
+					return xerrors.Errorf("script %q is not executable. See https://coder.com/docs/v2/latest/dotfiles for information on how to resolve the issue.", script)
+				}
+
 				// it is safe to use a variable command here because it's from
 				// a filtered list of pre-approved install scripts
 				// nolint:gosec
diff --git a/docs/dotfiles.md b/docs/dotfiles.md
index 15332229d3c07..af87e116bb853 100644
--- a/docs/dotfiles.md
+++ b/docs/dotfiles.md
@@ -60,3 +60,27 @@ sudo apt update
 # Install some of my favorite tools every time my workspace boots
 sudo apt install -y neovim fish cargo
 ```
+
+## Setup script support
+
+User can setup their dotfiles by creating one of the following script files in their dotfiles repo:
+
+- `install.sh`
+- `install`
+- `bootstrap.sh`
+- `bootstrap`
+- `script/bootstrap`
+- `setup.sh`
+- `setup`
+- `script/setup`
+
+If any of the above files are found (in the specified order), Coder will try to execute the first match. After the first match is found, other files will be ignored.
+
+The setup script must be executable, otherwise the dotfiles setup will fail. If you encounter this issue, you can fix it by making the script executable using the following commands:
+
+```shell
+cd <path_to_dotfiles_repo>
+chmod +x <script_name>
+git commit -m "Make <script_name> executable" <script_name>
+git push
+```