- Published on
GitLab Slack dispatch_failed: Checks for Self-Managed
- Authors

- Name
- Maruan
On GitLab Self-Managed, /gitlab failed with the error "dispatch_failed" points at the GitLab for Slack app setup on the instance and at the network path between Slack and GitLab, not at a merge request event rule. Check the app configuration and two-way connectivity with Slack before touching any project setting.
This runbook walks through that order. It keeps what GitLab documents separate from what we propose as a diagnostic check, and it never asks you to disable TLS, authentication or a firewall. Where a check is our suggestion rather than a documented cause, it says so.
Short answer: what dispatch_failed means on Self-Managed
dispatch_failed is the message Slack shows when a slash command could not be delivered to or handled by the app behind it. GitLab lists it as a known symptom: slash commands might return /gitlab failed with the error "dispatch_failed" in Slack. The same symptom appears under the administration troubleshooting section, which tells you where GitLab expects you to look: the instance, not a single project.
That matters because the error is about the command never completing. It says nothing about whether a merge request event would post to a channel. Treat these as separate problems.
The order we suggest:
Confirm the app is enabled and configured on the instance.
Confirm you are using your own private Slack app.
Confirm Slack and GitLab can reach each other in both directions.
Run /gitlab help, then one safe read-only command.
Stop at the first check that fails.
Check 1: Is the GitLab for Slack app enabled and configured on the instance?
Start in the admin area, because that is where the documented setup lives. Go to Admin > Settings > General > GitLab for Slack app, and confirm the Enable GitLab for Slack app option is selected.
Then check the app details you entered. They come from the private Slack app you created, found under App Credentials in Slack. The documentation names that app GitLab (<your host name>), so open the matching app in your Slack app management page and compare it to what the instance holds.
Two habits keep this safe:
Never paste the client secret or signing secret into a ticket, chat or screenshot. Compare by eye, or re-enter the value from the Slack app page if you suspect a typo.
If you change a value, save the settings and retry /gitlab help before changing anything else. One change per test tells you which one mattered.
After saving, run /gitlab help in Slack. GitLab documents this as the configuration test; the expected response is a list of available commands.
Is the old GitLab Slack notifications integration deprecated?
GitLab has moved Slack to the GitLab for Slack app, which handles both slash commands and notifications, and the older Slack notifications integration is the legacy path. If a project still uses the legacy integration, recreate it through the GitLab for Slack app in project integration settings. Do not disable TLS or authentication to work around errors during the move.
How do I connect a Slack workspace to a GitLab project?
Open the project, go to Settings, then Integrations, and choose GitLab for Slack app. Select Install GitLab for Slack app, select the intended workspace on the Slack confirmation page, and select Allow. Configure notification events and channels separately in the integration settings. An administrator must enable the integration at instance level first on Self-Managed. Afterwards run /gitlab help in Slack to confirm the link works. Test command routing independently of notification delivery.
Check 2: Are you using your own private Slack app, not the Slack App Directory app?
On Self-Managed, you need your own private Slack app. The GitLab for Slack app in the Slack App Directory works with GitLab.com only, so installing it from the directory against a Self-Managed instance will not give you working slash commands.
A practical way to check: in Slack, open the list of installed apps in your workspace. If the app that answers /gitlab is the directory listing rather than the one named for your own GitLab host, you have found a likely mismatch. This is a diagnostic suggestion, not a documented cause of dispatch_failed, but it is cheap to rule out.
If you do have a private app, confirm that the app installed in the workspace is the same one whose credentials sit on the instance. A second, half-configured app with a similar name is an easy mistake in a workspace where several people have experimented. For the difference between slash commands and notifications at the setup level, see GitLab Slack Slash Commands vs Notifications: Setup Explained.
How do I set up GitLab for Slack on Self-Managed?
On Self-Managed, create your own Slack app, then enter its client ID, client secret and signing secret in the instance's Slack integration settings. Install it to your workspace and authorise each project from its integration settings. The Slack App Directory app is built for GitLab.com, so it will not reach a private instance. Keep TLS on, use your real instance URL for the redirect and request URLs, and confirm Slack can reach GitLab over the network.
Does the Slack Marketplace app add GitLab Duo, and does it matter for dispatch_failed?
The Slack Marketplace app is aimed at GitLab.com, and GitLab Duo features in Slack depend on that app plus your GitLab plan and version. The dispatch_failed symptom alone does not establish whether GitLab Duo is involved. Look at the private Slack app, instance settings and the network path between Slack and GitLab instead of installing the Marketplace app.
Check 3: Can GitLab and Slack reach each other both ways?
GitLab documents the connectivity requirement plainly: the app needs inbound and outbound connections between GitLab and Slack. For slash commands, the GitLab instance must be allowed to receive requests from https://slack.com.
This is the check most likely to explain a slash command that fails while everything on the instance looks right. A slash command is Slack calling your GitLab host. If a reverse proxy, a firewall rule or a private-only DNS name blocks that inbound call, Slack reports dispatch_failed.
Proposed checks, all read-only:
From a machine on the instance network, confirm the GitLab host can make an outbound HTTPS request to slack.com.
Ask whoever owns your edge or proxy whether requests from slack.com can reach your GitLab URL from the public internet, and whether the hostname Slack uses resolves publicly.
Look at your proxy or load balancer access log while someone runs /gitlab help. A request that arrives and fails is a different problem from no request arriving at all.
Don't guess at IP allowlists. Work with your network team on what your policy permits. Leave TLS verification, authentication and the firewall switched on while you test.
Check 4: Run /gitlab help, then one safe read-only command
Use /gitlab help as the first live test. When the app is wired up correctly, it returns the list of available commands. If that list comes back, the dispatch path works and your problem is elsewhere.
If /gitlab help also returns dispatch_failed, go back to checks 1 to 3. The failure is at the instance or network layer.
Once help works, run one harmless read command against a project you can already access, such as showing a known non-sensitive issue. The slash commands page lists what is available and shows that project commands take a project full path by default. Pick something that only reads data.
Avoid commands that write or deploy while you are diagnosing. A deploy command, for example, tries to find a manual deployment action in the pipeline, which is not something to trigger as a connectivity test. Reading an issue proves the full round trip without changing anything.
If /gitlab help works but a project command fails: project or alias not found
If help works but a project command fails, read the exact error before choosing the next check. GitLab documents a distinct error for it: some Slack commands need a project full path or alias, and they fail with a "Project or alias not found" message when the project cannot be found.
Check these in order:
The full path is spelled exactly as it appears in GitLab, including the group and any subgroups.
If you use an alias, it was created for that project and typed the same way.
The GitLab for Slack app is enabled for that project.
For the specific project or alias not found error, start with the documented project lookup checks rather than changing firewall rules.
If commands work but MR notifications are missing
Working slash commands and missing merge request notifications are separate paths. Commands are inbound from Slack. Notifications are outbound from your instance, and they also depend on per-project configuration and channel setup.
We already cover that case in GitLab Slack Test Works but Merge Request Notifications Missing, so use that guide rather than repeating it here. The point for this runbook is the split: a healthy /gitlab help tells you nothing about whether MR events will post.
Optional: one updating card per PR or MR with MergeMe
If your real goal is seeing merge requests in Slack rather than running slash commands, MergeMe is a separate route. It shows GitHub pull requests and GitLab merge requests in Slack as one card per PR or MR that updates in place, and it supports GitHub.com, GitLab.com and self-hosted GitLab in one workspace.
It does not repair the native /gitlab slash commands. If you want those commands, fix dispatch_failed with the checks above. MergeMe is for the review-visibility side.
Fix the instance and the network path first, then decide if you need more
dispatch_failed on Self-Managed is an instance and connectivity problem until proven otherwise: enable and configure the app under Admin > Settings > General, use your own private Slack app, and make sure Slack can call your host while your host can call Slack. Confirm the help response first, then test the project command and notification paths independently.
FAQs
What does GitLab Slack dispatch_failed mean on Self-Managed?
It means a /gitlab slash command could not be delivered to or completed by the app. GitLab lists it as a known symptom of the GitLab for Slack app. On Self-Managed, check the instance app configuration and whether Slack can reach your GitLab host before suspecting any merge request event rule.
Can I use the GitLab for Slack app from the Slack App Directory on Self-Managed?
No. The directory app works with GitLab.com only. On Self-Managed, create a private copy of the app from GitLab’s manifest, configure it under Admin > Settings > General > GitLab for Slack app using its credentials, and install it in your workspace through Admin > Settings > Integrations > GitLab for Slack app.
Which network connections does the GitLab for Slack app need?
GitLab documents that notifications need outbound requests from your instance to https://slack.com, while slash commands and other features need inbound requests from https://slack.com to your instance. If the inbound path is blocked, commands fail even when notifications work. Do not disable TLS or firewalls to test.
/gitlab help works but another command fails. Is it still dispatch_failed?
Not necessarily. A successful /gitlab help checks basic command routing but does not diagnose every later failure. Read the exact error. For project or alias not found, check the full project path, configured alias and whether the app is enabled for that project.
Does MergeMe fix GitLab slash command errors?
No. MergeMe does not repair native /gitlab slash commands. It shows GitHub pull requests and GitLab merge requests in Slack as one updating card per PR or MR, and supports GitHub.com, GitLab.com and self-hosted GitLab.