Teslamate crashes when using postgres with unix socket connection: connect raised KeyError exception: key :username not found

[esclear]

Is there an existing issue for this?

• I have checked the existing issues and discussions, and I can confirm that there are no duplicates.

What happened?

I am trying to run teslamate on a system that already hosts a Postgres database for several other applications and is also backed up frequently.
That server only allows connections to the unix socket and doesn't open a TCP socket / port, as all applications using the server are running on the same machine.

I've configured Teslamate as follows:

DATABASE_SOCKET_DIR=/run/postgresql
DATABASE_USER=teslamate
DATABASE_NAME=teslamate
DATABASE_PASS=<password>

Upon starting teslamate, the postgrex connect call fails with connect raised KeyError exception: key :username not found. (full error below).
It seems that postgrex is expecting a username (and likely password, too) for its connect call, which are not provided.

I am aware that one usually uses peer authentication for database connections via the socket, however, that's not always possible.
One example is running applications, such as teslamate in this case, within docker and mounting the postgresql socket into the container.
In this case, peer authentication will not work and one needs to fall back to username and password.
However, teslamate / postgrex doesn't even start to attempt a connection to postgresql here.

Expected Behavior

Teslamate doesn't crash but starts normally.

Can the issue reliably be reproduced?

Yes

Steps To Reproduce the issue

No response

Relevant log output

** (RuntimeError) connect raised KeyError exception: key :username not found. The exception details are hidden, as they may contain sensitive data such as database credentials. You may set :show_sensitive_data_on_connection_error to true when starting your connection if you wish to see all of the details
    (elixir 1.19.5) lib/keyword.ex:608: Keyword.fetch!/2
    (postgrex 0.22.0) lib/postgrex/protocol.ex:864: Postgrex.Protocol.startup/2
    (postgrex 0.22.0) lib/postgrex/protocol.ex:760: Postgrex.Protocol.handshake/3
    (postgrex 0.22.0) lib/postgrex/protocol.ex:229: Postgrex.Protocol.connect_endpoints/6
    (db_connection 2.9.0) lib/db_connection/connection.ex:80: DBConnection.Connection.handle_event/4
    (stdlib 5.2.3.5) gen_statem.erl:1397: :gen_statem.loop_state_callback/11
    (stdlib 5.2.3.5) proc_lib.erl:241: :proc_lib.init_p_do_apply/3
2026-04-16 22:22:03.739 [notice] Application teslamate exited: exited in: TeslaMate.Application.start(:normal, [])
    ** (EXIT) exited in: DBConnection.Holder.checkout(#PID<0.2481.0>, [log: #Function<14.97393993/1 in Ecto.Adapters.SQL.with_log/4>, pool: DBConnection.ConnectionPool, repo: TeslaMate.Repo, pool_size: 10, timeout: 60000])
        ** (EXIT) killed
Kernel pid terminated (application_controller) ("{application_start_failure,teslamate,{bad_return,{{'Elixir.TeslaMate.Application',start,[normal,[]]},{'EXIT',{killed,{'Elixir.DBConnection.Holder',checkout,[<0.2481.0>,[{log,#Fun<Elixir.Ecto.Adapters.SQL.14.97393993>},{pool,'Elixir.DBConnection.ConnectionPool'},{repo,'Elixir.TeslaMate.Repo'},{pool_size,10},{timeout,60000}]]}}}}}}")

Crash dump is being written to: erl_crash.dump...done

Screenshots

n/a

Additional data

n/a

Type of installation

Docker (https://docs.teslamate.org/docs/installation/docker/)

Version

3.0.0 (MCU2 / pr4453)

PostgreSQL version

18

Are you running latest major supported PostgreSQL version?

• I run the latest major supported PostgreSQL version

Are you using a reverse Proxy for TeslaMate?

Yes (specify in next field)

Details about your reverse Proxy if applicable

not relevant

[JakobLichterfeld]

Thanks for your report. Not reporducible with correct PosgreSQL server config and unix domain socket. Please double check your PostgreSQL server config.

[esclear]

Can you elaborate on what a correct postgres config looks like?
Does the user in your tests have a password?

This exact postgres configuration works for other services I'm running through the same mechanism.

[esclear]

Looking at the NixOS module, my configuration is not that dissimilar from it:

• I have a number of additional extensions (vectorchord, postgis) enabled
• I have a number of additional databases configured
• Connection happens via UDS
• I don't have peer authentication for the teslamate user enabled (as I don't have a dedicated user for it)

The first two should really not be the problem, so I think the actual problem is in fact the fourth point and that teslamate doesn't allow to provide user credentials when connecting via a socket.