Azure Cloud Shell: Fix Common Errors & Setup Issues
Why Azure Cloud Shell Problems Happen
You opened the Azure portal, clicked the Cloud Shell icon in the top navigation bar, and got… nothing. Or a spinning wheel. Or a cryptic error about a storage account that you don't remember setting up. I've seen this exact situation play out dozens of times , and the frustrating part is that Azure Cloud Shell problems almost never come with a helpful error message. You just get a red banner or a blank terminal window and zero explanation for what went wrong.
So what actually is Azure Cloud Shell? It's an authenticated, browser-based terminal that Microsoft hosts for you. You get either a Bash or PowerShell environment , your choice, pre-loaded with Azure CLI, Azure PowerShell, Terraform, Docker, kubectl, and a long list of other tools. You don't install anything locally. You don't configure credentials. You just open a browser tab and you're connected to a live Azure session with your own identity.
That sounds simple. The reality is that Azure Cloud Shell has several moving parts under the hood, and any one of them can break silently. Here are the root causes I see most often:
- Storage account not provisioned or deleted. Azure Cloud Shell requires an Azure Files share to persist your
$HOMEdirectory across sessions. If that storage account was never created, got deleted, or lost its connection to Cloud Shell, you'll hit errors every time you try to start a session. - Session timeout confusion. Cloud Shell sessions end automatically after 20 minutes of no interactive activity. This is a hard limit, not configurable. People often mistake a timed-out session for a connectivity problem.
- Subscription or permission issues. Cloud Shell runs under your Azure identity. If your account doesn't have permission to create a storage account in the selected subscription, the initial setup will fail and leave you with a broken shell.
- Browser or network restrictions. Cloud Shell is a browser-based terminal. Corporate firewalls, strict Content Security Policy headers, or extensions like ad blockers can silently break the WebSocket connection the terminal depends on.
- Ephemeral session misunderstanding. If you chose to start Cloud Shell without a storage account, you're in an ephemeral session. Files you save there disappear when you close the window, and a lot of users don't realize they made that choice months ago.
- Azure: drive stale state in PowerShell. The Azure drive in PowerShell Cloud Shell doesn't auto-refresh. People navigate to
Azure:, see outdated resource listings, and think something is broken when it just needs a manual refresh.
None of these issues get flagged clearly in the Azure portal. Microsoft's error messages for Cloud Shell tend to be generic, "something went wrong" or "unable to start session", which makes diagnosing the actual cause harder than it needs to be. That's what this guide is for.
If you're dealing with other Azure headaches beyond Cloud Shell, browse all Microsoft fix guides →, there's likely a dedicated article for whatever else is hitting you.
The Quick Fix, Try This First
Before going deep into diagnostics, try the reset that solves roughly 60% of Azure Cloud Shell issues I encounter: close the current Cloud Shell session completely, clear your browser cache for the Azure portal domain, and reopen Cloud Shell from shell.azure.com directly rather than from inside the portal.
Here's the exact sequence:
- Click the X button in the Cloud Shell panel to close the current session, don't just minimize it.
- In Chrome: press
Ctrl + Shift + Delete→ set time range to Last hour → check Cached images and files and Cookies and other site data forportal.azure.comonly → click Clear data. - Navigate directly to shell.azure.com in a new tab. This bypasses any portal-specific rendering issues.
- Sign in if prompted. Cloud Shell will authenticate automatically using your Azure account.
- If you're asked to set up a storage account again, that means your previous one was disconnected, go through the setup wizard, which takes about 90 seconds.
If you hit the same error after this, the problem is deeper, usually the storage account itself or a permissions issue. Keep reading for the step-by-step breakdown.
One thing worth doing before you go further: check whether you're on Bash or PowerShell. You can switch between them using the dropdown at the top-left of the Cloud Shell toolbar. Some commands and behaviors, like the Azure: drive, only exist in the PowerShell environment. Mixing them up is a surprisingly common source of "something's broken" moments.
Ctrl+Shift+P) and run Azure: Open Bash in Cloud Shell.
This is the single most common cause of Azure Cloud Shell not connecting. Cloud Shell needs an Azure Files share mounted to persist your $HOME directory, the 5 GB that follows you from session to session. When that link breaks, Cloud Shell can't start a persistent session.
To check your storage account status:
- In the Azure portal, go to All resources and search for the storage account that Cloud Shell created. It typically has a name starting with
csfollowed by a string of random characters (e.g.,cs1a2b3c4d5e6f). - If you can't find it, it may have been deleted. That explains everything.
- If it exists, open it and navigate to File shares. Look for a share named something like
cs-yourupn-subscription-xxxx. Confirm it's there and shows a quota of 6 GB (Azure sets it slightly above the 5 GB limit). - If the file share is missing, you'll need to recreate it or let Cloud Shell reprovision it. Close Cloud Shell completely, reopen it at shell.azure.com, and click Show advanced settings when prompted. You can point Cloud Shell to an existing storage account or let it create a new one.
If you're seeing an error like "Storage account creation failed" during setup, it usually means your account doesn't have the Contributor role on the target subscription or resource group. Check your role assignments under Subscriptions → Access control (IAM). You need at minimum Contributor at the resource group level where the storage account will be created.
When it's working, Cloud Shell will open with a prompt that shows your username and the mounted path. You'll see something like /home/yourname in Bash or PS /home/yourname> in PowerShell. That confirms $HOME is live and persisted.
If your Azure Cloud Shell session keeps dropping, and you haven't touched it in a while, this is almost certainly the 20-minute timeout. Cloud Shell sessions end automatically after 20 minutes of no interactive activity. That's a hard limit set by Microsoft, it's not a bug, it's by design, and there's no setting to extend it.
I know this is frustrating, especially when you're in the middle of a long script run and you step away for a meeting. Here's how to work around it:
For long-running commands, use tmux, it's already preinstalled in Cloud Shell. Start a tmux session before running your command:
tmux new-session -s mysessionRun your command inside tmux. If your Cloud Shell session times out, reopen Cloud Shell and reattach:
tmux attach-session -t mysessionYour process will still be running inside tmux even after the terminal disconnected. This is the cleanest way to handle long-running tasks in Cloud Shell without babysitting the window.
For keeping a session alive during active work, just interact with the terminal every few minutes. Even pressing Enter on an empty command line counts as activity and resets the timer.
For automation and scheduled tasks, Cloud Shell is not the right tool. It's designed for interactive use. If you need unattended Azure automation, look at Azure Automation runbooks, GitHub Actions with Azure login, or Azure DevOps pipelines, these don't time out because they're not session-based.
After reconnecting to a timed-out session, you'll be placed back in your $HOME directory. If you had a storage account mounted, all your files will still be there. The timeout only ends the shell process, it doesn't affect your persistent storage.
One of the most underrated sources of Azure Cloud Shell confusion is being in the wrong shell environment. Azure Cloud Shell gives you two choices: Bash (running on Azure Linux) and PowerShell 7.4. They share the same $HOME storage, but they behave very differently, and some features only exist in one of them.
To switch, click the dropdown in the top-left of the Cloud Shell toolbar that shows either Bash or PowerShell. Select the other one. Cloud Shell will restart the session in the new environment. Your files in $HOME will still be there because both shells share the same mounted file share.
The Azure drive (Azure:) only exists in PowerShell. If you're trying to navigate Azure resources like a filesystem, browsing Compute, Network, Storage in a directory-like structure, you need PowerShell. Switch to the Azure drive with:
cd Azure:And return home with:
cd ~If you've navigated to Azure: and your resources look stale or incomplete, run:
dir -ForceThat forces a refresh of the Azure resource view. The Azure: drive doesn't update automatically, you have to trigger it manually. Changes you made in the Azure portal or via PowerShell cmdlets will show up after this refresh.
Azure CLI (az commands) works in both Bash and PowerShell. Azure PowerShell cmdlets (like Get-AzVM) also work in both, but they're more natural in the PowerShell environment. If you're running a Bash script that includes az commands and it's failing, confirm you're actually in Bash, if you're in PowerShell, the Bash syntax may not parse correctly.
After switching shells, you should see the new prompt style. Bash will show something like yourname@Azure:~$ and PowerShell will show PS /home/yourname>.
Azure Cloud Shell comes with an impressive collection of tools preinstalled, but sometimes you need something that isn't there. Maybe it's a specific Python library, a newer version of a CLI tool, or a package your team's scripts depend on. Here's how to handle it correctly without hitting the wall.
The critical constraint: you cannot install anything that requires root (sudo). Cloud Shell runs as a regular Linux user with standard permissions. Any package that needs to write to /usr/, /etc/, or other system directories will fail.
What you can install:
Python packages, install to your user directory:
pip3 install --user package-namePowerShell modules, install to your user module path:
Install-Module -Name ModuleName -Scope CurrentUserNode.js packages, global installs work because npm's global prefix points to your user directory in Cloud Shell:
npm install -g package-nameBinaries via wget or curl, download to $HOME/bin and make them executable:
mkdir -p $HOME/bin
wget -O $HOME/bin/mytool https://example.com/path/to/binary
chmod +x $HOME/bin/mytoolTo see what's already installed, use these commands depending on what you're looking for:
# List TDNF packages (Azure Linux package manager)
tdnf list
# List Python packages
pip3 list
# List PowerShell modules
Get-Module -ListAvailableOne important note: anything you install in Cloud Shell outside of $HOME will not survive the next session. The machine hosting your session is temporary, only your $HOME directory (mounted from Azure Files) persists. That means you'll want to put install commands in a startup script like $HOME/.bashrc or $HOME/.bash_profile so they run automatically each time a new session starts.
Azure Cloud Shell automatically authenticates you using your Azure account. That's one of its biggest advantages, you don't paste tokens, run az login, or configure service principals. When authentication breaks, it's usually an external cause: your session expired in the portal, your account has MFA requirements that got triggered mid-session, or your Azure subscription changed status.
If you see errors like "AuthorizationFailed" or "Credentials have expired" inside a running Cloud Shell session, here's the fastest fix:
- Close the Cloud Shell panel entirely.
- Sign out of the Azure portal (top-right avatar → Sign out).
- Sign back in. Complete any MFA prompts fully.
- Reopen Cloud Shell. It will inherit your fresh authentication token automatically.
If you're using Azure CLI inside Cloud Shell and getting auth errors despite the above, try running:
az account showThis tells you which subscription and tenant Cloud Shell thinks you're authenticated against. If it's wrong, for example, pointing to a subscription you no longer have access to, switch it:
az account list --output table
az account set --subscription "Your Subscription Name or ID"For Azure PowerShell specifically, check your context:
Get-AzContextIf the context shows the wrong subscription or is empty, set it explicitly:
Set-AzContext -SubscriptionId "your-subscription-id"For open-source tools like Terraform and Ansible that are preconfigured for authentication in Cloud Shell, re-authenticating through the portal and reopening Cloud Shell is almost always enough to restore their access. Cloud Shell handles the token injection for these tools automatically, you shouldn't need to manually configure credentials for them.
After fixing authentication, test with a simple command like az group list in Bash or Get-AzResourceGroup in PowerShell. If you get a list of resource groups back, authentication is working correctly.
Advanced Troubleshooting
If the steps above didn't resolve your Azure Cloud Shell issue, you're dealing with something more environmental, usually network-level restrictions, subscription-level policy enforcement, or storage account configuration edge cases. Let's get into those.
Corporate Firewall and Proxy Interference
Azure Cloud Shell is a browser-based terminal that relies on WebSocket connections. Corporate firewalls that do SSL inspection or block non-HTTP WebSocket upgrades will silently break Cloud Shell. The terminal will either hang on "Connecting…" or connect and then immediately drop.
Test this by opening Cloud Shell on a mobile hotspot or home network. If it works there but not on your corporate network, your firewall is the culprit. You'll need to work with your network team to allowlist the Cloud Shell endpoints, specifically *.console.azure.com and *.servicebus.windows.net.
As a workaround, Cloud Shell is also accessible through the Visual Studio Code Azure Account extension. Some corporate proxies that block browser WebSocket connections allow them through VS Code's network stack. It's worth trying before escalating a ticket.
Azure Policy Restrictions Blocking Storage Account Creation
If you work in an enterprise Azure environment, there may be Azure Policy assignments that restrict where storage accounts can be created, what SKUs are allowed, or what regions are permitted. When Cloud Shell tries to provision its storage account during first-time setup and hits one of these policies, it fails, often without a clear error message.
To investigate: go to Azure portal → Policy → Compliance and filter by your subscription. Look for any policies marked as Non-compliant related to storage. If you find one, you have two options: ask your Azure administrator to create an exemption for Cloud Shell's resource group, or manually create a compliant storage account and point Cloud Shell to it using the Show advanced settings option during setup.
$HOME Image Corruption
Your $HOME directory is stored as an .img file inside your Azure File share. This is an unusual design, it means $HOME is essentially a disk image mounted at session start. In rare cases, this image can become corrupted, usually if a session was force-terminated mid-write.
Symptoms of image corruption: Cloud Shell connects, but your home directory is empty, or you see I/O errors when trying to access files. To diagnose this, open your storage account in the Azure portal, navigate to the Cloud Shell file share, and look for the .img file. If it's there but Cloud Shell isn't loading it correctly, you may need to delete it and let Cloud Shell recreate an empty $HOME. Back up any files first by downloading them through the Upload/Download feature in the Cloud Shell toolbar.
Running Cloud Shell Commands Non-Interactively
Some teams try to automate tasks by scripting against Cloud Shell directly, this isn't how it's meant to be used and leads to unpredictable results. Cloud Shell is designed for interactive sessions. For non-interactive Azure automation, use Azure Automation, GitHub Actions with the azure/login action, or a local shell with a configured service principal. These are the right tools for CI/CD pipelines and scheduled tasks.
Prevention & Best Practices
Most Azure Cloud Shell headaches are preventable with a bit of upfront setup. Once you've got Cloud Shell running reliably, here's how to keep it that way.
Tag your Cloud Shell resource group. When Cloud Shell creates its storage account, it puts it in a resource group (usually named cloud-shell-storage-<region>). Add a tag like Environment: CloudShell-DoNotDelete to that resource group. This prevents accidental deletion by subscription cleanup scripts or well-meaning colleagues running cost optimization sweeps. Losing that storage account means losing your $HOME files, preventable with a tag.
Back up important files regularly. Your $HOME directory has a 5 GB limit. It's easy to fill it up with downloaded files, cloned repos, and build artifacts. Use the Cloud Shell toolbar's Download button to export important scripts and configs to your local machine. Alternatively, push your Cloud Shell scripts to a GitHub repository, git is preinstalled, and this gives you proper version control.
Store secrets properly. Don't put API keys, passwords, or SSH private keys as plain text files in your $HOME directory. The official recommendation is to use Azure Key Vault. Retrieve secrets at runtime with:
az keyvault secret show --name MySecret --vault-name MyVault --query value -o tsvThis keeps sensitive credentials out of your file share entirely.
Know the cost. The Cloud Shell compute (the machine running your session) is completely free. You do pay for the Azure Files storage account that holds your $HOME, but at 5 GB, this is typically under $1/month. If you have multiple subscriptions with Cloud Shell set up, check whether you have duplicate storage accounts and consolidate them if cost is a concern.
Use the Cloud Shell editor for config files. Cloud Shell includes a graphical text editor accessible via the code command. It's cleaner than vim or nano for editing YAML, JSON, and Bicep files inline, especially for deployment configs where formatting mistakes are costly.
code deployment.yaml- Tag your Cloud Shell resource group with
DoNotDeleteto prevent accidental cleanup - Put custom tool installs in
~/.bashrcor~/.bash_profileso they survive session resets - Use Azure Key Vault for secrets instead of plain text files in
$HOME - Use
tmuxfor any command that runs longer than 15 minutes to survive timeout events
Frequently Asked Questions
What is Azure Cloud Shell and do I need to install anything to use it?
Azure Cloud Shell is a browser-based, authenticated terminal for managing Azure resources. You access it from portal.azure.com, shell.azure.com, the Azure mobile app, or the Visual Studio Code Azure Account extension. You don't install anything locally, Microsoft hosts and manages the environment for you. It comes pre-loaded with Azure CLI, Azure PowerShell, Terraform, Docker, kubectl, git, and dozens of other tools. You choose whether to run Bash or PowerShell, and Cloud Shell authenticates automatically using your Azure identity.
Why does my Azure Cloud Shell session keep disconnecting after 20 minutes?
This is expected behavior, Azure Cloud Shell sessions time out automatically after 20 minutes of no interactive activity. This limit is set by Microsoft and can't be changed. To keep a session alive, interact with the terminal at least every 20 minutes. For long-running commands, use tmux (which is preinstalled), start your process inside a tmux session, and if the terminal disconnects, reattach with tmux attach-session -t yoursession after reopening Cloud Shell. Your process will keep running inside tmux even when the outer session times out.
Do my files saved in Azure Cloud Shell stay there after I close the browser?
It depends on whether you have a storage account configured. If you set up Cloud Shell with an attached Azure Files storage account (the default path), yes, your $HOME directory is persisted across sessions as an image file in that file share. You'll have up to 5 GB of storage. If you chose to start without storage (the ephemeral session option), then no, all files are deleted when you close the window. To check which mode you're in, look for a mounted clouddrive directory in your home folder. If it exists, you have persistent storage.
Is there a cost for using Azure Cloud Shell?
The compute that runs your Cloud Shell session is completely free, Microsoft covers the hosting cost. What you do pay for is the Azure Files storage account that Cloud Shell uses to persist your $HOME directory. At 5 GB of storage, this is typically less than $1 per month at standard Azure storage pricing. If you use Cloud Shell without a storage account (ephemeral mode), there's no cost at all, but your files won't persist between sessions.
Why is my Azure: drive in PowerShell not showing updated resources?
The Azure drive (Azure:) in PowerShell Cloud Shell doesn't refresh automatically. Changes you make in the Azure portal or through Azure PowerShell cmdlets won't appear in the Azure: drive listing until you manually force a refresh. Run dir -Force while inside the Azure drive to trigger an update. This is documented behavior, the drive reflects a cached snapshot of your Azure resources, not a live view. If you're managing resources that change frequently, it's often cleaner to just use Get-AzResource cmdlets directly rather than relying on the filesystem-like view.
Can I install my own tools in Azure Cloud Shell?
Yes, with an important limitation: you can only install tools that don't require root (sudo) access. Cloud Shell runs as a standard Linux user, so you can't write to system directories like /usr/bin or /etc. What you can do: install Python packages with pip3 install --user, install PowerShell modules with Install-Module -Scope CurrentUser, install Node packages with npm install -g, or download binaries directly to $HOME/bin. Put your install commands in ~/.bashrc or ~/.bash_profile to make them run automatically at the start of each new session, since only your $HOME directory persists.