When you want to mention a user on Mastodon who is not on your home instance, the standard @username format will not work because Mastodon requires the full account address. Tagging someone across instances means you must include their instance domain in the mention. This article explains the correct syntax for cross-instance mentions, shows you how to add them in the web interface and mobile apps, and covers common mistakes that prevent the tag from working.
Key Takeaways: Cross-Instance Mention Syntax for Mastodon
- @username@instance.domain: The full address format required to tag a user on a different Mastodon instance.
- Auto-complete after typing the full address: The compose box suggests the user once you enter the full @username@instance.domain and pauses briefly.
- Search bar on the instance: Use the search box to look up the full address before composing a post if you need to verify the account exists.
Why a Simple @username Fails Across Instances
Mastodon is a federated network made up of thousands of independent instances. Each instance stores its own user database. When you type @username in a post, Mastodon searches only the local database of your home instance. If the user belongs to another instance, the local database has no record of that username, so the mention appears as plain text instead of a clickable link.
To tag a user on a different instance, you must provide the full address: @username@instance.domain. This address works like an email address. The first part is the username on the remote instance, and the second part is the domain of that remote instance. When you post with this format, Mastodon fetches the remote user’s profile from their home instance and creates a proper mention notification for them.
The Difference Between Local and Federated Mentions
A local mention uses only the username part, such as @alice. Mastodon resolves this against your instance’s local database. A federated mention uses the full address, such as @alice@social.example.com. Mastodon sends a request to social.example.com to verify the account and then links the mention. Both types of mentions appear as clickable links in the post, but only the federated format works for users outside your home instance.
Steps to Tag a User on a Different Instance
- Open the compose box on your home instance
Go to your Mastodon instance in a web browser or open the official Mastodon mobile app. Tap the compose button to create a new post. - Type the full address starting with @
Enter @username@instance.domain exactly. For example, if the user has the username techwriter on the instance fosstodon.org, type @techwriter@fosstodon.org. Do not add spaces before or after the address. - Wait for the auto-complete suggestion
After you type the full address and pause for one to two seconds, Mastodon displays a drop-down suggestion with the user’s display name and avatar. Tap or click the suggestion to confirm the mention. If no suggestion appears, the remote account may not exist or your instance may not have discovered it yet. - Continue composing your post
Add any additional text, hashtags, or media. The mention appears as a highlighted link in the compose box. You can add multiple cross-instance mentions in the same post by repeating steps 2 and 3 for each user. - Post the message
Click the publish button. Mastodon sends the post to your home instance, which then pushes the mention notification to the remote instance.
Manually Searching for a Remote User Before Mentioning
If the auto-complete does not work, you can force Mastodon to discover the remote user by searching for their full address first. Type the full address into the search bar on your home instance. Mastodon performs a webfinger lookup against the remote instance. If the account exists, it appears in the search results. After this search, the auto-complete suggestion works immediately in the compose box.
Common Mistakes That Break Cross-Instance Mentions
Mention Does Not Appear as a Link After Posting
If the mention appears as plain text like @username@instance.domain instead of a clickable link, the remote account does not exist or the address contains a typo. Verify the exact username and domain. Use the search bar to look up the account before posting. Also check that the remote instance is not defederated from your home instance. Defederation blocks all communication between instances, including mentions.
User Does Not Receive a Notification
Even when the mention appears as a link, the remote user may not receive a notification if their instance has disabled notifications for mentions from unknown accounts. This setting is controlled by the remote user’s preferences. You cannot fix this from your side. The mention still creates a visible link in the post, but the user may not see it unless they manually search for it.
Auto-Complete Suggests the Wrong User
If you have previously interacted with a user on a different instance, Mastodon may cache that account locally. When you type part of the address, the auto-complete might suggest a cached account with a similar username. Always verify the full domain in the suggestion before selecting it. Hover over the suggestion to see the full address in the tooltip.
Cross-Instance Mention vs Local Mention
| Item | Local Mention | Cross-Instance Mention |
|---|---|---|
| Syntax | @username | @username@instance.domain |
| User must be on same instance | Yes | No |
| Auto-complete works immediately | Yes | Only after the remote account is cached |
| Notification delivered to remote user | Not applicable | Yes, unless blocked by remote instance settings |
| Mention appears as clickable link | Yes | Yes, if the remote account exists |
Now you can tag any Mastodon user regardless of which instance they call home. Use the full @username@instance.domain format and wait for the auto-complete to confirm the account. If the mention does not resolve, search for the user manually using the search bar on your home instance. This forces Mastodon to fetch the remote profile and cache it locally for future mentions.