This document describes an older version of Celery (2.1). For the latest stable version please go here.

Executable Jobs - celery.worker.job

exception celery.worker.job.AlreadyExecutedError

Tasks can only be executed once, as they might change world-wide state.

exception celery.worker.job.InvalidTaskError

The task has invalid data or is not properly constructed.

class celery.worker.job.TaskRequest(task_name, task_id, args, kwargs, on_ack=<function noop at 0x4741320>, retries=0, delivery_info=None, hostname=None, email_subject=None, email_body=None, logger=None, eventer=None, eta=None, expires=None, **opts)

A request for task execution.


Kind of task. Must be a name registered in the task registry.


UUID of the task.


List of positional arguments to apply to the task.


Mapping of keyword arguments to apply to the task.


Callback called when the task should be acknowledged.


The original message sent. Used for acknowledging the message.


Set to True if the task has been executed. A task should only be executed once.


Additional delivery info, e.g. the contains the path from producer to consumer.


Set to True if the task has been acknowledged.

acknowledged = False
email_body = '\nTask %(name)s with id %(id)s raised exception:\n%(exc)r\n\n\nTask was called with args: %(args)s kwargs: %(kwargs)s.\n\nThe contents of the full traceback was:\n\n%(traceback)s\n\n-- \nJust to let you know,\nceleryd at %(hostname)s.\n'
email_subject = ' [celery@%(hostname)s] Error: Task %(name)s (%(id)s): %(exc)s\n '
error_msg = ' Task %(name)s[%(id)s] raised exception: %(exc)s\n%(traceback)s\n '
execute(loglevel=None, logfile=None)

Execute the task in a WorkerTaskTrace.

  • loglevel – The loglevel used by the task.
  • logfile – The logfile used by the task.
execute_using_pool(pool, loglevel=None, logfile=None)

Like execute(), but using the multiprocessing pool.

  • pool – A multiprocessing.Pool instance.
  • loglevel – The loglevel used by the task.
  • logfile – The logfile used by the task.
executed = False
extend_with_default_kwargs(loglevel, logfile)

Extend the tasks keyword arguments with standard task arguments.

Currently these are logfile, loglevel, task_id, task_name, task_retries, and delivery_info.

See for more information.

classmethod from_message(message, message_data, on_ack=<function noop at 0x4741320>, logger=None, eventer=None, hostname=None)

Create a TaskRequest from a task message sent by celery.messaging.TaskPublisher.

Raises UnknownTaskError:
 if the message does not describe a task, the message is also rejected.

:returns TaskRequest:

on_accepted(*a, **kw)

Handler called when task is accepted by worker pool.


The handler used if the task raised an exception.


The handler used if the task was successfully processed ( without raising an exception).

repr_result(result, maxlen=46)
retry_msg = ' Task %(name)s[%(id)s] retry: %(exc)s\n '
send_error_email(task, context, exc, whitelist=None, enabled=False, fail_silently=True)
send_event(type, **fields)
success_msg = ' Task %(name)s[%(id)s] succeeded in %(runtime)ss: %(return_value)s\n '
time_start = None
class celery.worker.job.WorkerTaskTrace(*args, **kwargs)

Wraps the task in a jail, catches all exceptions, and saves the status and result of the task execution to the task meta backend.

If the call was successful, it saves the result to the task result backend, and sets the task status to "SUCCESS".

If the call raises celery.exceptions.RetryTaskError, it extracts the original exception, uses that as the result and sets the task status to "RETRY".

If the call results in an exception, it saves the exception as the task result, and sets the task status to "FAILURE".

  • task_name – The name of the task to execute.
  • task_id – The unique id of the task.
  • args – List of positional args to pass on to the function.
  • kwargs – Keyword arguments mapping to pass on to the function.

the evaluated functions return value on success, or the exception instance on failure.


Execute, trace and store the result of the task.

execute_safe(*args, **kwargs)

Same as execute(), but catches errors.

handle_failure(exc, type_, tb, strtb)

Handle exception.

handle_retry(exc, type_, tb, strtb)

Handle retry exception.

handle_success(retval, *args)

Handle successful execution.

celery.worker.job.execute_and_trace(task_name, *args, **kwargs)

This is a pickleable method used as a target when applying to pools.

It’s the same as:

>>> WorkerTaskTrace(task_name, *args, **kwargs).execute_safe()

Previous topic

Worker Message Listener - celery.worker.listener

Next topic

Worker Controller Threads - celery.worker.controllers

This Page