Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

Postfix 550 5.1.1 User unknown: local recipient table or virtual mailbox table

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

Postfix accepted the domain and then refused the recipient because the address is not in the table for that domain class. In smtpd_check.c the text is User unknown, and when show_user_unknown_table_name is yes (the default) it adds either in local recipient table or in virtual mailbox table. The class string for a recipient is Recipient address. The enhanced status the source passes on this path is 5.1.1. The numerical code is unknown_local_recipient_reject_code or unknown_virtual_mailbox_reject_code. Both default to 550. The status keeps its 5.1.1 form only while the SMTP code is 5xx: in smtpd_check_reject the first digit of the enhanced status is forced to match the SMTP code, so with the code set to 450 the reply is 450 4.1.1.

So the line you are looking for is 550, 5.1.1, and Recipient address rejected: User unknown in local recipient table or in virtual mailbox table.

That is a permanent reject. The sender's server should not keep retrying it as a temporary failure. A different check, reject_unverified_recipient, uses unverified_recipient_reject_code, default 450, and by default includes the address-verification details rather than this table name.

What the symptom means

A local recipient is one whose domain matches mydestination, inet_interfaces or proxy_interfaces. local_recipient_maps defaults to proxy:unix:passwd.byname and alias_maps. If that value is non-empty, the SMTP server looks the recipient up and rejects unknown local recipients. postconf says other interfaces, such as the sendmail command, may still accept an unknown recipient. The SMTP rejection is what remote servers see.

To turn the local check off, postconf says to set local_recipient_maps empty. The note on luser_relay says that if you deliver accounts that are not in the UNIX password file, you must set local_recipient_maps empty, or the SMTP server rejects mail for non-UNIX accounts with User unknown in local recipient table.

A virtual mailbox domain is one listed in virtual_mailbox_domains. The SMTP server validates recipients with virtual_mailbox_maps and rejects mail for recipients that are not listed. unknown_virtual_mailbox_reject_code is the code when the domain matches and the maps do not contain the address. The default is 550.

show_user_unknown_table_name (default yes) puts the table name in the User unknown response. postconf says the extra detail helps troubleshooting and also reveals information that is nobody else's business. If the phrase stops at User unknown and does not name a table, that parameter has been set to no, or the reply came from a different check.

reject_unverified_recipient is not this map check. postconf describes it as rejecting a recipient when mail to that address is known to bounce, or when the destination is not reachable. The default numerical code is 450. The default reason text is empty, and the response then includes the verification details. A 450 with verification wording is the probe. A 550 that names the local recipient table or the virtual mailbox table is the map.

postconf's example for the local code is unknown_local_recipient_reject_code = 450. It says the default 550 rejects the mail, and that it is safer to start with 450 so you have time to see whether local_recipient_maps is right.

Likely causes

Cause What you see How to confirm
The local part is not in the UNIX accounts or aliases User unknown in local recipient table The domain is in mydestination, and the name is not in passwd or alias_maps
The address is missing from virtual_mailbox_maps User unknown in virtual mailbox table The domain is in virtual_mailbox_domains, and the map has no entry
Accounts live only in the virtual map, but the domain is still local Local-table reject for a mailbox you created as virtual mydestination contains the domain, so the local map is consulted
You use luser_relay for users who are not in the password file Local-table reject, as the luser_relay note describes local_recipient_maps is still the default
Address verification, not the map 450, and the text is verification detail, not the table name unverified_recipient_reject_code is 450 by default

Prove the cause before changing anything

All of these are read-only.

1. Read which table the reply named. Keep the full SMTP text. in local recipient table and in virtual mailbox table are different maps.

2. Print the maps and the codes.

postconf -n
postconf -d local_recipient_maps
postconf -d unknown_local_recipient_reject_code
postconf -d unknown_virtual_mailbox_reject_code
postconf -d show_user_unknown_table_name
postconf -d unverified_recipient_reject_code

-n shows what this host set. -d shows the defaults. A local reject with the default maps means the lookup against the password file and the aliases did not match.

3. Decide the domain class before you edit a map. postconf: a recipient is local when its domain matches mydestination, proxy_interfaces or inet_interfaces. A virtual mailbox recipient matches virtual_mailbox_domains. Adding the address to the wrong map does not clear the reject.

Fix

Adding the missing address to the map the error named is the lasting fix. While you check a local map you do not yet trust, the postconf example uses a temporary code instead. A local address has to be found in the UNIX password database or in alias_maps. A virtual mailbox address has to be in virtual_mailbox_maps. With the default virtual_mailbox_domains = $virtual_mailbox_maps, postconf says the tables also need an entry whose left-hand side is the bare domain.

Save the explicit settings first. The answer goes to its own file:

postconf -n > postconf-before.txt

Add the address to the map

Save the map file you are about to edit. Read the value of the map the error named with this read-only command:

postconf virtual_mailbox_maps alias_maps

A value can start with a table type and a colon, written <type>:<map-file>. The file to copy is the path after the colon. Copy it:

cp -a <map-file> <map-file>.before

Risk: the next step edits the live recipient map and rebuilds its index. Once the index is rebuilt and Postfix is reloaded, a wrong line can accept mail for an address that should not exist, or hide a good address. Edit only the one line you mean to add.

Add the address to the map file with your editor. postmap(1) says a table entry has the form key whitespace value, so copy the shape of an existing line. Then rebuild the index. For an indexed virtual_mailbox_maps file, postmap(1) creates or updates the index. Give it the same <type>:<map-file> value that the parameter holds:

postmap <type>:<map-file>

For alias_maps, run newaliases instead. Then run postfix reload.

To undo it: put the saved copy back with cp -a <map-file>.before <map-file>, run postmap <type>:<map-file> again (or newaliases for the aliases file), and run postfix reload.

Use a temporary code while you check a local map

Save the explicit settings first, if you have not already done so above. The answer goes to its own file:

postconf -n > postconf-before-code.txt

Risk: the next command edits main.cf and reloads Postfix. Setting unknown_local_recipient_reject_code to 450 makes unknown local recipients a temporary failure, with reply 450 4.1.1. Remote servers will keep retrying, including addresses that are genuinely wrong.

The postconf example, for the period when you are still checking the map, is a temporary code. postconf(1) writes it with -e:

postconf -e 'unknown_local_recipient_reject_code=450'
postfix reload

postfix reload re-reads the configuration.

To undo it: if postconf-before-code.txt contains unknown_local_recipient_reject_code, run postconf -e 'unknown_local_recipient_reject_code=<saved value>' with the value from that file, and postfix reload. If the saved file did not contain this parameter, remove it instead with postconf -X unknown_local_recipient_reject_code and reload, which restores the default.

postconf gives this advice to start with 450 only for the local code. For unknown_virtual_mailbox_reject_code it gives no such advice, so when the text says in virtual mailbox table, fix the virtual map above and leave that code alone.

postconf describes setting local_recipient_maps empty as the way to turn the local unknown-user check off, so that Postfix accepts SMTP recipients for local domains that are not in the password file or the aliases. That removes the protection for every local address, and the steps above do not use it.

Example (illustrative): mail to sam@example.com returns 550 5.1.1 and User unknown in virtual mailbox table. example.com is in virtual_mailbox_domains. The mailbox map lists sam.example.com without the @. The lookup does not match. The administrator adds sam@example.com to virtual_mailbox_maps, rebuilds the indexed file, and reloads. The 450 setting is not used, because the map was wrong and the address should exist.

Confirm the fix

  1. The SMTP reply no longer says User unknown for that address.
  2. postconf -n shows the code you intend. If you only fixed the map, the reject code is still 550, and a different unknown address is still rejected.
  3. If you set 450 while testing, put 550 back after the map is right, or the next unknown address will be deferred instead of rejected.

What to watch afterwards

  • A new local account that is not in the password file or the aliases will hit the same 550 until the map lists it.
  • Virtual domains need the address in virtual_mailbox_maps, not only a mailbox directory on disk.
  • Leaving the code at 450 queues mail for every unknown local recipient. That is the safer setting only while you are checking the map.
  • A 450 that talks about verification is reject_unverified_recipient. Changing local_recipient_maps will not clear it.

Risks and limits

  • The table phrase is added only when show_user_unknown_table_name is yes. A reply that does not name the table still uses User unknown, and you then have to read the domain class yourself.
  • Relay domains use a third phrase, in relay recipient table, and unknown_relay_recipient_reject_code, also default 550. The cases above are the local recipient table and the virtual mailbox table.
  • A 550 5.1.1 from a different mail server is not this check. The table phrase is Postfix's own text, and it appears only when show_user_unknown_table_name is yes.

Sources