Issue running Formance Stack locally – payments services fail to start (branch release/v3.0)

[mpyatishev]

Hi everyone 👋

I’m trying to run the Formance Stack locally using the docker-compose.yml file from the root of the repository on branch release/v3.0.
However, some services fail to start properly — specifically the payments-api and payments-connectors containers exit with an error.

Here’s what I’m doing:

git clone https://github.com/formancehq/stack.git
cd stack
docker compose up

And here’s the console output I get:

payments-migrate-1 exited with code 0
payments-connectors-1  | Error: unknown command "connectors" for "payments"
payments-connectors-1  | Run 'payments --help' for usage.
payments-api-1         | Error: unknown command "api" for "payments"
payments-api-1         | Run 'payments --help' for usage.
payments-connectors-1 exited with code 1
payments-api-1 exited with code 1

It seems like the payments binary no longer supports these subcommands, or the docker-compose file might be outdated.

Could you please clarify:
• Is the docker-compose.yml in release/v3.0 still up-to-date?
• If not, what is the recommended way to spin up the full stack locally for development/testing now?
• Are there updated images or configuration files I should use instead?

Thanks a lot for your help! 🙏

[aalloiteau]

Hi @mpyatishev , could you check stack 3.1 ?

[mpyatishev]

Hi! Yes, thank you — after switching to tag 3.1, the stack started successfully.

Just to clarify: am I right that the fctl utility only works with the cloud version and cannot be used with a self-hosted deployment?

Thanks again!

[aalloiteau]

Yes, exactly, Fctl cannot be used with the local version of the stack

[mpyatishev]

Got it, thanks for confirming!

One more question — is it possible to use the Python SDK with a self-hosted deployment of the stack, or is it also limited to the cloud version?

Thanks!

[aalloiteau]

You can use SDKs on a local stack. You just need to target your localhost url

from formance_sdk_python import SDK
from formance_sdk_python.models import operations, shared

LEDGER_NAME = "ledger-001"
SERVER_URL = "http://localhost:8080"

def run():
    client = SDK(server_url=SERVER_URL)

    # Create a ledger
    # Define bucket to have ledger-001 on its own PG schema, otherwise _default is used
    client.ledger.v2.create_ledger(
        request=operations.V2CreateLedgerRequest(
            ledger=LEDGER_NAME,
            v2_create_ledger_request=shared.V2CreateLedgerRequest(
                features={}, metadata={}, bucket="ledger-001-bucket"
            ),
        )
    )

if __name__ == "__main__":
    run()

[mpyatishev]

Perfect, thank you for the clarification and example! Everything’s clear now.

Appreciate your help 🙂

[formance-support[bot]]

Speculation based on limited information: The task appears to be troubleshooting why payments-api and payments-connectors containers fail to start when running docker compose up from the formancehq/stack repository on the release/v3.0 branch, with specific errors indicating "unknown command 'api'" and "unknown command 'connectors'" for the payments binary.
Major clarifications needed / open questions:

• Repository mismatch: I investigated formancehq/payments but the ticket explicitly mentions formancehq/stack - these appear to be different repositories with potentially different docker-compose configurations
• Container naming discrepancy: Ticket mentions payments-api and payments-connectors containers, but the payments repo uses payments and payments-worker - suggests different orchestration
• Branch context unclear: Is release/v3.0 referring to the stack repo or payments repo branch?
  Alternative interpretations:

1. The formancehq/stack repository contains a legitimately broken docker-compose.yml file
2. Container images might be mismatched versions between stack and payments repositories
3. The stack repository might require different setup procedures than the individual payments service
4. This could be a documentation issue where setup instructions are missing or outdated

Investigation limitation: I do not have access to the formancehq/stack repository mentioned in the ticket, so cannot analyze the actual docker-compose.yml file causing the issue.
What I found in formancehq/payments (may not be relevant):

• Current payments CLI structure uses payments serve and payments worker commands
• Docker-compose.yml shows containers named payments and payments-worker
• Requires plugin compilation (just compile-plugins) and STACK_PUBLIC_URL environment variable
  Critical gap: Without access to the stack repository, I cannot determine if the container names, command structure, or setup requirements are the same as the individual payments service.

Escalation required: This ticket requires investigation of the formancehq/stack repository's docker-compose.yml file and documentation to provide an accurate solution.
Potential approaches (unconfirmed):

1. Check stack repository docker-compose.yml - Compare container commands against current payments binary CLI structure
2. Verify image versions - Ensure container images match expected command structure
3. Review stack setup documentation - Check if additional setup steps are required
4. Test with different branch - Verify if issue exists on main/master branch
   Cannot provide specific file changes or code modifications without understanding the actual stack repository structure and how it differs from the individual payments service repository.
   Design decisions needed:

• Whether to update docker-compose commands or container images
• What setup prerequisites apply to the stack repository
• Whether additional environment variables or compilation steps are required

Looks good? Click here to start a Devin session

Needs work? Follow up in Devin Spaces or by replying with @devin

💡 This scoping used your organization's Jira knowledge — review and update it to improve future scoping